.. _cookiecutter-integration:

======================================
Cookiecutter templates with PyScaffold
======================================

`Cookiecutter`_ is a flexible utility that allows the definition of templates
for a diverse range of software projects.
On the other hand, PyScaffold is focused in a good out-of-the-box
experience for developing distributable Python packages (exclusively).
Despite the different objectives, it is possible to combine the power of both
tools to create a custom Python project setup. For instance, the following
command creates a new package named ``mypkg``, that uses a Cookiecutter template,
but is enhanced by PyScaffold features:

.. code-block:: bash

    $ putup mypkg --cookiecutter gh:audreyr/cookiecutter-pypackage

.. note::

    Although using Cookiecutter templates is a viable solution to customize
    a project that was set up with PyScaffold, the recommended way is to help
    improve PyScaffold by contributing an :ref:`extension <extensions>`.


Suitable templates
==================

Note that PyScaffold will overwrite some files generated by Cookiecutter,
like ``setup.py``, the ``__init__.py`` file under the package folder
and most of the ``docs`` folder, in order to provide `setuptools_scm`_
and `sphinx`_ integration.
Therefore not all Cookiecutter templates are suitable for this approach.

Ideally, interoperable templates should focus on the file structure inside the
package folder instead of packaging or distributing, since PyScaffold already
handles it under-the-hood. However, the following files can be safely
generated by a template (will not be overwritten)::

    <project root>/docs/index.rst
    <project root>/tests/conftest.py
    <project root>/README.rst
    <project root>/AUTHORS.rst
    <project root>/LICENSE.txt
    <project root>/CHANGES.rst
    <project root>/setup.cfg
    <project root>/requirements.txt
    <project root>/test-requirements.txt
    <project root>/.coveragerc

In addition, PyScaffold runs Cookiecutter with the ``--no-input`` flag
activated and thus the user is not prompted for manual configuration. Instead,
PyScaffold injects the following parameters::

    author
    email
    project_name
    package_name
    project_short_description

Accordingly, the template file structure should be similar to::

    cookiecutter-something/
    └── {{cookiecutter.project_name}}/
        └── {{cookiecutter.package_name}}/
            └── ...

See `Cookiecutter`_ for more information about template creation.

.. _Cookiecutter: https://cookiecutter.readthedocs.org
.. _setuptools_scm: https://pypi.python.org/pypi/setuptools_scm/
.. _sphinx: http://www.sphinx-doc.org
