User Guide

What is Cookiecutter?

Cookiecutter is a command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.

Installation

Cookiecutter is available on PyPI. Use pip to download and install:

$ pip install cookiecutter

Usage

You can generate a new project from a template by using the following command:

$ cookiecutter https://github.com/tox-dev/cookiecutter-tox-plugin

This will not only git clone the template but also start the generation process.

Template Variables

Each Cookiecutter template uses variables, which are specified in the template, that it replaces in all of the directory and file names, but also in text such as source code or markdown formats.

Plugin Details

Cookiecutter prompts you for information regarding your plugin based on aforementioned variables:

full_name [Oliver Bestwalter]: Somebody Else
email [oliver@bestwalter.de]: somebody@elsewhere.com
github_username [obestwalter]: somebody_else
plugin_name [foobar]: awesome
pkg_name [tox_foobar]: 
module_name [plugin]: 
entry_point [tox_foobar.plugin]: 
short_description [A simple plugin to use with tox]: 
version [0.1.0]: 
tox_version [3.0.0]: 
Select docs_tool:
1 - mkdocs
2 - sphinx
3 - none
Choose from 1, 2, 3 [1]:
Select license:
1 - MIT
2 - BSD-3
3 - GNU GPL v3.0
4 - Apache Software License 2.0
5 - Mozilla Public License 2.0
Choose from 1, 2, 3, 4, 5 [1]: 

INFO:post_gen_project:Initializing docs for mkdocs
INFO:post_gen_project:Moving doc_sources/mkdocs/index.md to docs/index.md.
INFO:post_gen_project:Moving doc_sources/mkdocs/mkdocs.yml to /home/ob/do/tox-dev/tox-foobar/mkdocs.yml.
INFO:post_gen_project:Remove temporary folder: doc_sources
INFO:post_gen_project:Remove temporary folder: licenses
INFO:post_gen_project:Remove temporary folder: macros

The values in the square brackets (f.i. [foobar]) are defaults for the according variables.

Project Generation

Once you answered the questions, Cookiecutter renders the the project:

tox-awesome/
├── tox.ini
├── .travis.yml
├── appveyor.yml
├── mkdocs.yml
├── LICENSE
├── MANIFEST.in
├── README.rst
├── docs
│   └── index.md
├── setup.py
├── tests
│   ├── conftest.py
│   └── test_tox_awesome.py
└── tox_awesome
    ├── __init__.py
    └── plugin.py

There you go - you just created a minimal tox plugin: