.. _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's features:

.. code-block:: bash

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

This is roughly equivalent to first create a project using the Cookiecutter
template and convert it to PyScaffold afterwards:

.. code-block:: bash

    $ cookiecutter --no-input gh:audreyr/cookiecutter-pypackage project_name=mypkg
    $ putup mypkg --force

.. note::

    For complex Cookiecutter templates calling ``cookiecutter`` and ``putup``
    separately may be a better option, since it is possible to answer
    specific template questions or at least set values for Cookiecutter
    variables.

.. warning::

    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
``src`` folder instead of packaging or distributing, since PyScaffold already
handles it under-the-hood. This also means that your template should adhere to
the src-layout if you want to generate files within your Python package.

.. 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

   TODO: Review this piece of doc after decision regarding #102

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}}/
        └── src/
            └── {{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
