diff --git a/docs/advanced/calling_from_python.rst b/docs/advanced/calling_from_python.rst index 4c7f2e9ad..b497b6bf0 100644 --- a/docs/advanced/calling_from_python.rst +++ b/docs/advanced/calling_from_python.rst @@ -3,7 +3,9 @@ Calling Cookiecutter Functions From Python ------------------------------------------ -You can use Cookiecutter from Python:: +You can use Cookiecutter from Python: + +.. code-block:: python from cookiecutter.main import cookiecutter @@ -13,6 +15,6 @@ You can use Cookiecutter from Python:: # Create project from the cookiecutter-pypackage.git repo template cookiecutter('https://github.com/audreyr/cookiecutter-pypackage.git') -This is useful if, for example, you're writing a web framework and need to -provide developers with a tool similar to `django-admin.py startproject` or -`npm init`. +This is useful if, for example, you're writing a web framework and need to provide developers with a tool similar to `django-admin.py startproject` or `npm init`. + +See the :ref:`API Reference ` for more details. diff --git a/docs/advanced/choice_variables.rst b/docs/advanced/choice_variables.rst index ccb35d4bf..706d53947 100644 --- a/docs/advanced/choice_variables.rst +++ b/docs/advanced/choice_variables.rst @@ -1,17 +1,21 @@ .. _choice-variables: -Choice Variables (1.1+) ------------------------ +Choice Variables +---------------- -Choice variables provide different choices when creating a project. Depending on a user's choice -the template renders things differently. +*New in Cookiecutter 1.1* + +Choice variables provide different choices when creating a project. +Depending on a user's choice the template renders things differently. Basic Usage ~~~~~~~~~~~ Choice variables are regular key / value pairs, but with the value being a list of strings. -For example, if you provide the following choice variable in your ``cookiecutter.json``:: +For example, if you provide the following choice variable in your ``cookiecutter.json``: + +.. code-block:: JSON { "license": ["MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0"] @@ -28,8 +32,9 @@ you'd get the following choices when running Cookiecutter:: Depending on an user's choice, a different license is rendered by Cookiecutter. -The above ``license`` choice variable creates ``cookiecutter.license``, which -can be used like this:: +The above ``license`` choice variable creates ``cookiecutter.license``, which can be used like this: + +.. code-block:: html+jinja {%- if cookiecutter.license == "MIT" -%} # Possible license content here @@ -41,7 +46,10 @@ can be used like this:: Cookiecutter is using `Jinja2's if conditional expression `_ to determine the correct license. -The created choice variable is still a regular Cookiecutter variable and can be used like this:: +The created choice variable is still a regular Cookiecutter variable and can be used like this: + +.. code-block:: html+jinja + License ------- @@ -53,7 +61,9 @@ Overwriting Default Choice Values Choice Variables are overwritable using a :ref:`user-config` file. -For example, a choice variable can be created in ``cookiecutter.json`` by using a list as value:: +For example, a choice variable can be created in ``cookiecutter.json`` by using a list as value: + +.. code-block:: JSON { "license": ["MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0"] diff --git a/docs/advanced/copy_without_render.rst b/docs/advanced/copy_without_render.rst index 2cdb68084..5e4bc008d 100644 --- a/docs/advanced/copy_without_render.rst +++ b/docs/advanced/copy_without_render.rst @@ -5,7 +5,10 @@ Copy without Render *New in Cookiecutter 1.1* -To avoid rendering directories and files of a cookiecutter, the `_copy_without_render` key can be used in the `cookiecutter.json`. The value of this key accepts a list of Unix shell-style wildcards:: +To avoid rendering directories and files of a cookiecutter, the ``_copy_without_render`` key can be used in the ``cookiecutter.json``. +The value of this key accepts a list of Unix shell-style wildcards: + +.. code-block:: JSON { "project_slug": "sample", @@ -16,7 +19,12 @@ To avoid rendering directories and files of a cookiecutter, the `_copy_without_r ] } -**Note**: Only the content of the files will be copied without being rendered. The paths are subject to rendering. This allows you to write:: +**Note**: +Only the content of the files will be copied without being rendered. +The paths are subject to rendering. +This allows you to write: + +.. code-block:: JSON { "project_slug": "sample", @@ -25,4 +33,4 @@ To avoid rendering directories and files of a cookiecutter, the `_copy_without_r ] } -In this example, `{{cookiecutter.repo_name}}` will be rendered as expected but the html file content will be copied without rendering. +In this example, ``{{cookiecutter.repo_name}}`` will be rendered as expected but the html file content will be copied without rendering. diff --git a/docs/advanced/dict_variables.rst b/docs/advanced/dict_variables.rst index 1db841fa1..6142f4bd8 100644 --- a/docs/advanced/dict_variables.rst +++ b/docs/advanced/dict_variables.rst @@ -1,20 +1,21 @@ .. _dict-variables: -Dictionary Variables (1.5+) ---------------------------- +Dictionary Variables +-------------------- -Dictionary variables provide a way to define deep structured information when -rendering a template. +*New in Cookiecutter 1.5* + +Dictionary variables provide a way to define deep structured information when rendering a template. Basic Usage ~~~~~~~~~~~ -Dictionary variables are, as the name suggests, dictionaries of key-value -pairs. The dictionary values can, themselves, be other dictionaries and lists -- the data structure can be as deep as you need. +Dictionary variables are, as the name suggests, dictionaries of key-value pairs. +The dictionary values can, themselves, be other dictionaries and lists - the data structure can be as deep as you need. + +For example, you could provide the following dictionary variable in your ``cookiecutter.json``: -For example, you could provide the following dictionary variable in your -``cookiecutter.json``:: +.. code-block:: json { "project_slug": "new_project", @@ -38,8 +39,9 @@ For example, you could provide the following dictionary variable in your } -The above ``file_type`` dictionary variable creates -``cookiecutter.file_types``, which can be used like this:: +The above ``file_type`` dictionary variable creates ``cookiecutter.file_types``, which can be used like this: + +.. code-block:: html+jinja {% for extension, details in cookiecutter.file_types|dictsort %}
diff --git a/docs/advanced/directories.rst b/docs/advanced/directories.rst index cbec8e4ae..ba0596ded 100644 --- a/docs/advanced/directories.rst +++ b/docs/advanced/directories.rst @@ -1,14 +1,13 @@ .. _directories: -Organizing cookiecutters in directories (1.7+) ---------------------------------------------------- +Organizing cookiecutters in directories +--------------------------------------- *New in Cookiecutter 1.7* -Cookiecutter introduces the ability to organize several templates in one -repository or zip file, separating them by directories. This allows using -symlinks for general files. Here's an example repository demonstrating -this feature:: +Cookiecutter introduces the ability to organize several templates in one repository or zip file, separating them by directories. +This allows using symlinks for general files. +Here's an example repository demonstrating this feature:: https://github.com/user/repo-name.git ├── directory1-name/ @@ -18,6 +17,8 @@ this feature:: ├── {{cookiecutter.project_slug}}/ └── cookiecutter.json -To activate one of templates within a subdirectory, use the ``--directory`` option:: +To activate one of templates within a subdirectory, use the ``--directory`` option: + +.. code-block:: bash cookiecutter https://github.com/user/repo-name.git --directory="directory1-name" diff --git a/docs/advanced/hooks.rst b/docs/advanced/hooks.rst index c659fd407..d08cf9e75 100644 --- a/docs/advanced/hooks.rst +++ b/docs/advanced/hooks.rst @@ -1,12 +1,13 @@ .. _user-hooks: -Using Pre/Post-Generate Hooks (0.7.0+) -====================================== +Using Pre/Post-Generate Hooks +============================= -You can have Python or Shell scripts that run before and/or after your project -is generated. +*New in cookiecutter 0.7* -Put them in `hooks/` like this:: +You can have Python or Shell scripts that run before and/or after your project is generated. + +Put them in ``hooks/`` like this:: cookiecutter-something/ ├── {{cookiecutter.project_slug}}/ @@ -24,13 +25,11 @@ Shell scripts work similarly:: │ └── post_gen_project.sh └── cookiecutter.json -It shouldn't be too hard to extend Cookiecutter to work with other types of -scripts too. Pull requests are welcome. +It shouldn't be too hard to extend Cookiecutter to work with other types of scripts too. +Pull requests are welcome. -For portability, you should use Python scripts (with extension `.py`) for your -hooks, as these can be run on any platform. However, if you intend for your -template to only be run on a single platform, a shell script (or `.bat` file -on Windows) can be a quicker alternative. +For portability, you should use Python scripts (with extension `.py`) for your hooks, as these can be run on any platform. +However, if you intend for your template to only be run on a single platform, a shell script (or `.bat` file on Windows) can be a quicker alternative. Writing hooks ------------- @@ -40,25 +39,21 @@ Here are some details on how to write pre/post-generate hook scripts. Exit with an appropriate status ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Make sure your hook scripts work in a robust manner. If a hook script fails -(that is, `if it finishes with a nonzero exit status -`_), the project -generation will stop and the generated directory will be cleaned up. +Make sure your hook scripts work in a robust manner. +If a hook script fails (that is, `if it finishes with a nonzero exit status `_), the project generation will stop and the generated directory will be cleaned up. Current working directory ^^^^^^^^^^^^^^^^^^^^^^^^^ -When the hook scripts script are run, their current working directory is the -root of the generated project. This makes it easy for a post-generate hook to -find generated files using relative paths. +When the hook scripts script are run, their current working directory is the root of the generated project. +This makes it easy for a post-generate hook to find generated files using relative paths. Template variables are rendered in the script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Just like your project template, Cookiecutter also renders Jinja template -syntax in your scripts. This lets you incorporate Jinja template variables in -your scripts. For example, this line of Python sets ``module_name`` to the -value of the ``cookiecutter.module_name`` template variable: +Just like your project template, Cookiecutter also renders Jinja template syntax in your scripts. +This lets you incorporate Jinja template variables in your scripts. +For example, this line of Python sets ``module_name`` to the value of the ``cookiecutter.module_name`` template variable: .. code-block:: python @@ -67,9 +62,7 @@ value of the ``cookiecutter.module_name`` template variable: Example: Validating template variables -------------------------------------- -Here is an example of a pre-generate hook script, defined at -``hooks/pre_gen_project.py``, that validates a template variable before generating the -project: +Here is an example of a pre-generate hook script, defined at ``hooks/pre_gen_project.py``, that validates a template variable before generating the project: .. code-block:: python @@ -90,12 +83,10 @@ project: Example: Conditional files / directories ---------------------------------------- -Here is an example of a post-generate hook script, defined at -``hooks/post_gen_project.py``, on how to achieve conditional control of files and -directories after generating the project. +Here is an example of a post-generate hook script. +The file ``hooks/post_gen_project.py`` shows how to achieve conditional control of files and directories after generating the project. -The script ensures that the directory structure is as expected by -removing unwanted files and directories: +The script ensures that the directory structure is as expected by removing unwanted files and directories: .. code-block:: python diff --git a/docs/advanced/injecting_context.rst b/docs/advanced/injecting_context.rst index 32927c07f..5561b3d83 100644 --- a/docs/advanced/injecting_context.rst +++ b/docs/advanced/injecting_context.rst @@ -3,17 +3,30 @@ Injecting Extra Context ----------------------- -You can specify an `extra_context` dictionary that will override values from `cookiecutter.json` or `.cookiecutterrc`:: +You can specify an ``extra_context`` dictionary that will override values from ``cookiecutter.json`` or ``.cookiecutterrc``: - cookiecutter('cookiecutter-pypackage/', - extra_context={'project_name': 'TheGreatest'}) +.. code-block:: python + + cookiecutter( + 'cookiecutter-pypackage/', + extra_context={'project_name': 'TheGreatest'}, + ) + +This works as command-line parameters as well: + +.. code-block:: bash + + cookiecutter --no-input cookiecutter-pypackage/ project_name=TheGreatest + +You will also need to add these keys to the ``cookiecutter.json`` or ``.cookiecutterrc``. -You will also need to add these keys to the `cookiecutter.json` or `.cookiecutterrc`. Example: Injecting a Timestamp ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you have ``cookiecutter.json`` that has the following keys:: +If you have ``cookiecutter.json`` that has the following keys: + +.. code-block:: JSON { "timestamp": "{{ cookiecutter.timestamp }}" @@ -21,7 +34,9 @@ If you have ``cookiecutter.json`` that has the following keys:: This Python script will dynamically inject a timestamp value as the project is -generated:: +generated: + +.. code-block:: python from cookiecutter.main import cookiecutter @@ -34,6 +49,6 @@ generated:: How this works: -1. The script uses `datetime` to get the current UTC time in ISO format. -2. To generate the project, `cookiecutter()` is called, passing the timestamp - in as context via the `extra_context` dict. +1. The script uses ``datetime`` to get the current UTC time in ISO format. +2. To generate the project, ``cookiecutter()`` is called, passing the timestamp + in as context via the ``extra_context``` dict. diff --git a/docs/advanced/local_extensions.rst b/docs/advanced/local_extensions.rst index a90b04d7d..9a3d4b940 100644 --- a/docs/advanced/local_extensions.rst +++ b/docs/advanced/local_extensions.rst @@ -35,8 +35,8 @@ It will contain a ``main.py`` file, containing the following (for instance): This will register the ``foobar`` filter for the template. -For many cases, this will be unneccessarily complicated. It's likely that we'd only want to register a single function -as a filter. For this, we can use the ``simple_filter`` decorator: +For many cases, this will be unneccessarily complicated. +It's likely that we'd only want to register a single function as a filter. For this, we can use the ``simple_filter`` decorator: .. code-block:: json diff --git a/docs/advanced/new_line_characters.rst b/docs/advanced/new_line_characters.rst index 64f009898..e75ca9fcc 100644 --- a/docs/advanced/new_line_characters.rst +++ b/docs/advanced/new_line_characters.rst @@ -5,19 +5,22 @@ Working with line-ends special symbols LF/CRLF *New in Cookiecutter 2.0* -Before version 2.0 Cookiecutter silently used system line end character. -LF for POSIX and CRLF for Windows. Since version 2.0 this behaviour changed -and now can be forced at template level. +.. note:: -By default Cookiecutter now check every file at render stage and use same line -end as in source. This allow template developers to have both types of files in -the same template. Developers should correctly configure their `.gitattributes` -file to avoid line-end character overwrite by git. + Before version 2.0 Cookiecutter silently used system line end character. + LF for POSIX and CRLF for Windows. + Since version 2.0 this behaviour changed and now can be forced at template level. -Special template variable `_new_lines` was added in Cookiecutter 2.0. -Acceptable variables: `'\n\r'` for CRLF and `'\n'` for POSIX. +By default Cookiecutter checks every file at render stage and uses the same line end as in source. +This allow template developers to have both types of files in the same template. +Developers should correctly configure their ``.gitattributes`` file to avoid line-end character overwrite by git. -Here is example how to force line endings to CRLF on any deployment:: +The special template variable ``_new_lines`` enforces a specific line ending. +Acceptable variables: ``'\n\r'`` for CRLF and ``'\n'`` for POSIX. + +Here is example how to force line endings to CRLF on any deployment: + +.. code-block:: JSON { "project_slug": "sample", diff --git a/docs/advanced/private_variables.rst b/docs/advanced/private_variables.rst index 08ba9d943..6d17268b3 100644 --- a/docs/advanced/private_variables.rst +++ b/docs/advanced/private_variables.rst @@ -3,7 +3,12 @@ Private Variables ----------------- -Cookiecutter allows the definition private variables - those the user will not be required to fill in - by prepending an underscore to the variable name. These can either be not rendered, by using a prepending underscore, or rendered, prepending a double underscore. For example, the ``cookiecutter.json``:: +Cookiecutter allows the definition private variables by prepending an underscore to the variable name. +The user will not be required to fill those variables in. +These can either be not rendered, by using a prepending underscore, or rendered, prepending a double underscore. +For example, the ``cookiecutter.json``: + +.. code-block:: JSON { "project_name": "Really cool project", @@ -11,7 +16,9 @@ Cookiecutter allows the definition private variables - those the user will not b "__rendered": "{{ cookiecutter.project_name|lower }}" } -Will be rendered as:: +Will be rendered as: + +.. code-block:: JSON { "project_name": "Really cool project", @@ -21,7 +28,11 @@ Will be rendered as:: The user will only be asked for ``project_name``. -Non-rendered private variables can be used for defining constants. An example of where you may wish to use private **rendered** variables is creating a Python package repository and want to enforce naming consistency. To ensure the repository and package name are based on the project name, you could create a ``cookiecutter.json`` such as:: +Non-rendered private variables can be used for defining constants. +An example of where you may wish to use private **rendered** variables is creating a Python package repository and want to enforce naming consistency. +To ensure the repository and package name are based on the project name, you could create a ``cookiecutter.json`` such as: + +.. code-block:: JSON { "project_name": "Project Name", diff --git a/docs/advanced/replay.rst b/docs/advanced/replay.rst index 14afbfd24..426f0274e 100644 --- a/docs/advanced/replay.rst +++ b/docs/advanced/replay.rst @@ -9,7 +9,9 @@ On invocation **Cookiecutter** dumps a json file to ``~/.cookiecutter_replay/`` In other words, it persists your **input** for a template and fetches it when you run the same template again. -Example for a replay file (which was created via ``cookiecutter gh:hackebrot/cookiedozer``):: +Example for a replay file (which was created via ``cookiecutter gh:hackebrot/cookiedozer``): + +.. code-block:: JSON { "cookiecutter": { @@ -28,27 +30,31 @@ Example for a replay file (which was created via ``cookiecutter gh:hackebrot/coo To fetch this context data without being prompted on the command line you can use either of the following methods. -Pass the according option on the CLI:: +Pass the according option on the CLI: + +.. code-block:: bash cookiecutter --replay gh:hackebrot/cookiedozer Or use the Python API:: +.. code-block:: python + from cookiecutter.main import cookiecutter cookiecutter('gh:hackebrot/cookiedozer', replay=True) - -This feature is comes in handy if, for instance, you want to create a new project from an updated template. +This feature comes in handy if, for instance, you want to create a new project from an updated template. Custom replay file ~~~~~~~~~~~~~~~~~~ *New in Cookiecutter 2.0* -To specify a custom filename, you can use the ``--replay-file`` option:: +To specify a custom filename, you can use the ``--replay-file`` option: + +.. code-block:: bash cookiecutter --replay-file ./cookiedozer.json gh:hackebrot/cookiedozer -This may be useful to run the same replay file over several machines, in tests -or when a user of the template reports a problem +This may be useful to run the same replay file over several machines, in tests or when a user of the template reports a problem. diff --git a/docs/advanced/suppressing_prompts.rst b/docs/advanced/suppressing_prompts.rst index 1f73ff9fd..1064ad965 100644 --- a/docs/advanced/suppressing_prompts.rst +++ b/docs/advanced/suppressing_prompts.rst @@ -3,12 +3,14 @@ Suppressing Command-Line Prompts -------------------------------- -To suppress the prompts asking for input, use `no_input`. +To suppress the prompts asking for input, use ``no_input``. Basic Example: Using the Defaults ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Cookiecutter will pick a default value if used with `no_input`:: +Cookiecutter will pick a default value if used with ``no_input``: + +.. code-block:: python from cookiecutter.main import cookiecutter cookiecutter( @@ -16,18 +18,21 @@ Cookiecutter will pick a default value if used with `no_input`:: no_input=True, ) -In this case it will be using the default defined in `cookiecutter.json` or `.cookiecutterrc`. +In this case it will be using the default defined in ``cookiecutter.json`` or ``.cookiecutterrc``. .. note:: - values from `cookiecutter.json` will be overridden by values from `.cookiecutterrc` + values from ``cookiecutter.json`` will be overridden by values from ``.cookiecutterrc`` Advanced Example: Defaults + Extra Context ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you combine an `extra_context` dict with the `no_input` argument, you can programmatically create the project with a set list of context parameters and without any command line prompts:: +If you combine an ``extra_context`` dict with the ``no_input`` argument, you can programmatically create the project with a set list of context parameters and without any command line prompts: + +.. code-block:: JSON cookiecutter('cookiecutter-pypackage/', no_input=True, extra_context={'project_name': 'TheGreatest'}) -See the :ref:`API Reference ` for more details. + +See also :ref:`injecting-extra-content` and the :ref:`API Reference ` for more details. diff --git a/docs/advanced/template_extensions.rst b/docs/advanced/template_extensions.rst index 2e2273e8b..397460fa8 100644 --- a/docs/advanced/template_extensions.rst +++ b/docs/advanced/template_extensions.rst @@ -5,8 +5,8 @@ Template Extensions *New in Cookiecutter 1.4* -A template may extend the Cookiecutter environment with custom `Jinja2 extensions`_, -that can add extra filters, tests, globals or even extend the parser. +A template may extend the Cookiecutter environment with custom `Jinja2 extensions`_. +It can add extra filters, tests, globals or even extend the parser. To do so, a template author must specify the required extensions in ``cookiecutter.json`` as follows: @@ -20,12 +20,10 @@ To do so, a template author must specify the required extensions in ``cookiecutt On invocation Cookiecutter tries to import the extensions and add them to its environment respectively. -In the above example, Cookiecutter provides the additional tag `now`_, after -installing the `jinja2_time.TimeExtension`_ and enabling it in ``cookiecutter.json``. +In the above example, Cookiecutter provides the additional tag `now`_, after installing the `jinja2_time.TimeExtension`_ and enabling it in ``cookiecutter.json``. Please note that Cookiecutter will **not** install any dependencies on its own! -As a user you need to make sure you have all the extensions installed, before -running Cookiecutter on a template that requires custom Jinja2 extensions. +As a user you need to make sure you have all the extensions installed, before running Cookiecutter on a template that requires custom Jinja2 extensions. By default Cookiecutter includes the following extensions: @@ -38,8 +36,7 @@ By default Cookiecutter includes the following extensions: Jsonify extension ~~~~~~~~~~~~~~~~~ -The ``cookiecutter.extensions.JsonifyExtension`` extension provides a ``jsonify`` filter in templates -that converts a Python object to JSON: +The ``cookiecutter.extensions.JsonifyExtension`` extension provides a ``jsonify`` filter in templates that converts a Python object to JSON: .. code-block:: jinja @@ -56,10 +53,10 @@ Random string extension *New in Cookiecutter 1.7* -The ``cookiecutter.extensions.RandomStringExtension`` extension provides a ``random_ascii_string`` -method in templates that generates a random fixed-length string, optionally with punctuation. +The ``cookiecutter.extensions.RandomStringExtension`` extension provides a ``random_ascii_string`` method in templates that generates a random fixed-length string, optionally with punctuation. -Generate a random n-size character string. Example for n=12: +Generate a random n-size character string. +Example for n=12: .. code-block:: jinja @@ -71,8 +68,7 @@ Outputs: bIIUczoNvswh -The second argument controls if punctuation and special characters -``!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~`` should be present in the result: +The second argument controls if punctuation and special characters ``!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~`` should be present in the result: .. code-block:: jinja @@ -87,8 +83,7 @@ Outputs: Slugify extension ~~~~~~~~~~~~~~~~~ -The ``cookiecutter.extensions.SlugifyExtension`` extension provides a ``slugify`` filter in templates -that converts string into its underscored ("slugified") version: +The ``cookiecutter.extensions.SlugifyExtension`` extension provides a ``slugify`` filter in templates that converts string into its dashed ("slugified") version: .. code-block:: jinja @@ -100,16 +95,14 @@ Would output: it-s-a-random-version -It is diferent from a mere replace of spaces since it also trates some special characters -such as `'` in the example above. The function accepts all arguments that can be passed to -the `slugify` function of python-slugify. For example to change the output from -`it-s-a-random-version` to `it_s_a_random_version`, the parameter `separator='_'` would -be passed to `slugify()`. +It is different from a mere replace of spaces since it also trates some special characters such as ``'`` in the example above. +The function accepts all arguments that can be passed to the ``slugify`` function of `python-slugify`_. +For example to change the output from ``it-s-a-random-version``` to ``it_s_a_random_version``, the ``separator`` parameter would be passed: ``slugify(separator='_')``. .. _`Jinja2 extensions`: http://jinja.pocoo.org/docs/latest/extensions/ .. _`now`: https://github.com/hackebrot/jinja2-time#now-tag .. _`jinja2_time.TimeExtension`: https://github.com/hackebrot/jinja2-time -.. _`python-slugify`: https://github.com/un33k/python-slugify +.. _`python-slugify`: https://pypi.org/project/python-slugify UUID4 extension ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/advanced/templates_in_context.rst b/docs/advanced/templates_in_context.rst index faccb3c72..f324c60fe 100644 --- a/docs/advanced/templates_in_context.rst +++ b/docs/advanced/templates_in_context.rst @@ -4,20 +4,21 @@ Templates in Context Values -------------------------------- The values (but not the keys!) of `cookiecutter.json` are also Jinja2 templates. -Values from user prompts are added to the context immediately, such that one -context value can be derived from previous values. This approach can potentially -save your user a lot of keystrokes by providing more sensible defaults. +Values from user prompts are added to the context immediately, such that one context value can be derived from previous values. +This approach can potentially save your user a lot of keystrokes by providing more sensible defaults. Basic Example: Templates in Context -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python packages show some patterns for their naming conventions: -* a human-readable project name -* a lowercase, dashed repository name -* an importable, dash-less package name +- a human-readable project name +- a lowercase, dashed repository name +- an importable, dash-less package name -Here is a `cookiecutter.json` with templated values for this pattern:: +Here is a `cookiecutter.json` with templated values for this pattern: + +.. code-block:: JSON { "project_name": "My New Project", @@ -25,13 +26,12 @@ Here is a `cookiecutter.json` with templated values for this pattern:: "pkg_name": "{{ cookiecutter.project_slug|replace('-', '') }}" } -If the user takes the defaults, or uses `no_input`, the templated values will -be: +If the user takes the defaults, or uses `no_input`, the templated values will be: -* `my-new-project` -* `mynewproject` +- `my-new-project` +- `mynewproject` Or, if the user gives `Yet Another New Project`, the values will be: -* `yet-another-new-project` -* `yetanothernewproject` +- ``yet-another-new-project`` +- ``yetanothernewproject`` diff --git a/docs/advanced/user_config.rst b/docs/advanced/user_config.rst index a46dc95b6..c7a8e9826 100644 --- a/docs/advanced/user_config.rst +++ b/docs/advanced/user_config.rst @@ -1,18 +1,26 @@ .. _user-config: -User Config (0.7.0+) -==================== +User Config +=========== + +*New in Cookiecutter 0.7* If you use Cookiecutter a lot, you'll find it useful to have a user config file. By default Cookiecutter tries to retrieve settings from a `.cookiecutterrc` file in your home directory. -From version 1.3.0 you can also specify a config file on the command line via ``--config-file``:: +*New in Cookiecutter 1.3* + +You can also specify a config file on the command line via ``--config-file``. + +.. code-block:: bash - $ cookiecutter --config-file /home/audreyr/my-custom-config.yaml cookiecutter-pypackage + cookiecutter --config-file /home/audreyr/my-custom-config.yaml cookiecutter-pypackage -Or you can set the ``COOKIECUTTER_CONFIG`` environment variable:: +Or you can set the ``COOKIECUTTER_CONFIG`` environment variable: - $ export COOKIECUTTER_CONFIG=/home/audreyr/my-custom-config.yaml +.. code-block:: bash + + export COOKIECUTTER_CONFIG=/home/audreyr/my-custom-config.yaml If you wish to stick to the built-in config and not load any user config file at all, use the CLI option ``--default-config`` instead. Preventing Cookiecutter from loading user settings is crucial for writing integration tests in an isolated environment. @@ -36,7 +44,7 @@ Possible settings are: ``default_context``: A list of key/value pairs that you want injected as context whenever you generate a project with Cookiecutter. - These values are treated like the defaults in `cookiecutter.json`, upon generation of any project. + These values are treated like the defaults in ``cookiecutter.json``, upon generation of any project. ``cookiecutters_dir`` Directory where your cookiecutters are cloned to when you use Cookiecutter with a repo argument. ``replay_dir`` @@ -46,5 +54,7 @@ Possible settings are: A list of abbreviations for cookiecutters. Abbreviations can be simple aliases for a repo name, or can be used as a prefix, in the form ``abbr:suffix``. Any suffix will be inserted into the expansion in place of the text ``{0}``, using standard Python string formatting. - With the above aliases, you could use the `cookiecutter-pypackage` template simply by saying ``cookiecutter pp``, or ``cookiecutter gh:audreyr/cookiecutter-pypackage``. + With the above aliases, you could use the ``cookiecutter-pypackage`` template simply by saying ``cookiecutter pp``, or ``cookiecutter gh:audreyr/cookiecutter-pypackage``. The ``gh`` (GitHub), ``bb`` (Bitbucket), and ``gl`` (Gitlab) abbreviations shown above are actually **built in**, and can be used without defining them yourself. + +Read also: :ref:`injecting-extra-content` diff --git a/docs/tutorials/tutorial1.rst b/docs/tutorials/tutorial1.rst index 555753609..0871ca696 100644 --- a/docs/tutorials/tutorial1.rst +++ b/docs/tutorials/tutorial1.rst @@ -5,28 +5,25 @@ Getting to Know Cookiecutter .. note:: Before you begin, please install Cookiecutter 0.7.0 or higher. Instructions are in :doc:`../installation`. -Cookiecutter is a tool for creating projects from *cookiecutters* (project -templates). +Cookiecutter is a tool for creating projects from *cookiecutters* (project templates). What exactly does this mean? Read on! Case Study: cookiecutter-pypackage ----------------------------------- -*cookiecutter-pypackage* is a cookiecutter template that creates the starter -boilerplate for a Python package. +*cookiecutter-pypackage* is a cookiecutter template that creates the starter boilerplate for a Python package. -.. note:: There are several variations of it, but for this tutorial we'll use - the original version at https://github.com/audreyr/cookiecutter-pypackage/. +.. note:: + There are several variations of it. + For this tutorial we'll use the original version at https://github.com/audreyr/cookiecutter-pypackage/. Step 1: Generate a Python Package Project ------------------------------------------ -Open your shell and cd into the directory where you'd like to create a starter -Python package project. +Open your shell and cd into the directory where you'd like to create a starter Python package project. -At the command line, run the cookiecutter command, passing in the link to -cookiecutter-pypackage's HTTPS clone URL like this: +At the command line, run the cookiecutter command, passing in the link to cookiecutter-pypackage's HTTPS clone URL like this: .. code-block:: bash @@ -35,18 +32,17 @@ cookiecutter-pypackage's HTTPS clone URL like this: Local Cloning of Project Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, cookiecutter-pypackage gets cloned to `~/.cookiecutters/` (or equivalent -on Windows). Cookiecutter does this for you, so sit back and wait. +First, cookiecutter-pypackage gets cloned to `~/.cookiecutters/` (or equivalent on Windows). +Cookiecutter does this for you, so sit back and wait. Local Generation of Project ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When cloning is complete, you will be prompted to enter a bunch of values, such -as `full_name`, `email`, and `project_name`. Either enter your info, or simply -press return/enter to accept the default values. +When cloning is complete, you will be prompted to enter a bunch of values, such as `full_name`, `email`, and `project_name`. +Either enter your info, or simply press return/enter to accept the default values. -This info will be used to fill in the blanks for your project. For example, -your name and the year will be placed into the LICENSE file. +This info will be used to fill in the blanks for your project. +For example, your name and the year will be placed into the LICENSE file. Step 2: Explore What Got Generated ---------------------------------- @@ -58,8 +54,7 @@ In your current directory, you should see that a project got generated: $ ls boilerplate -Looking inside the `boilerplate/` (or directory corresponding to your `project_slug`) -directory, you should see something like this: +Looking inside the `boilerplate/` (or directory corresponding to your `project_slug`) directory, you should see something like this: .. code-block:: bash @@ -94,38 +89,38 @@ Notice how it was auto-populated with your (or my) name and email. Also take note of the fact that you are looking at a ReStructuredText file. Cookiecutter can generate a project with text files of any type. -Great, you just generated a skeleton Python package. How did that work? +Great, you just generated a skeleton Python package. +How did that work? Step 3: Observe How It Was Generated ------------------------------------ -Let's take a look at cookiecutter-pypackage together. Open https://github.com/audreyr/cookiecutter-pypackage in a new browser window. +Let's take a look at cookiecutter-pypackage together. +Open https://github.com/audreyr/cookiecutter-pypackage in a new browser window. {{ cookiecutter.project_slug }} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Find the directory called `{{ cookiecutter.project_slug }}`. Click on it. Observe -the files inside of it. You should see that this directory and its contents -corresponds to the project that you just generated. +Find the directory called `{{ cookiecutter.project_slug }}`. +Click on it. +Observe the files inside of it. +You should see that this directory and its contents corresponds to the project that you just generated. This happens in `find.py`, where the `find_template()` method looks for the first jinja-like directory name that starts with `cookiecutter`. AUTHORS.rst ~~~~~~~~~~~ -Look at the raw version of `{{ cookiecutter.project_slug }}/AUTHORS.rst`, at -https://raw.github.com/audreyr/cookiecutter-pypackage/master/%7B%7Bcookiecutter.project_slug%7D%7D/AUTHORS.rst. +Look at the raw version of `{{ cookiecutter.project_slug }}/AUTHORS.rst`, at https://raw.github.com/audreyr/cookiecutter-pypackage/master/%7B%7Bcookiecutter.project_slug%7D%7D/AUTHORS.rst. Observe how it corresponds to the `AUTHORS.rst` file that you generated. cookiecutter.json ~~~~~~~~~~~~~~~~~ -Now navigate back up to `cookiecutter-pypackage/` and look at the -`cookiecutter.json` file. +Now navigate back up to `cookiecutter-pypackage/` and look at the `cookiecutter.json` file. -You should see JSON that corresponds to the prompts and default values shown -earlier during project generation: +You should see JSON that corresponds to the prompts and default values shown earlier during project generation: .. code-block:: json @@ -147,13 +142,11 @@ earlier during project generation: Questions? ---------- -If anything needs better explanation, please take a moment to file an issue at https://github.com/audreyr/cookiecutter/issues with what could be improved -about this tutorial. +If anything needs better explanation, please take a moment to file an issue at https://github.com/audreyr/cookiecutter/issues with what could be improved about this tutorial. Summary ------- -You have learned how to use Cookiecutter to generate your first project from a -cookiecutter project template. +You have learned how to use Cookiecutter to generate your first project from a cookiecutter project template. -In Tutorial 2, you'll see how to create cookiecutters of your own, from scratch. +In tutorial 2 (:ref:`tutorial2`), you'll see how to create cookiecutters of your own, from scratch. diff --git a/docs/tutorials/tutorial2.rst b/docs/tutorials/tutorial2.rst index 830206788..53fcc1d21 100644 --- a/docs/tutorials/tutorial2.rst +++ b/docs/tutorials/tutorial2.rst @@ -1,3 +1,5 @@ +.. _tutorial2: + ================================== Create a Cookiecutter From Scratch ================================== @@ -5,8 +7,7 @@ Create a Cookiecutter From Scratch Step 1: Name Your Cookiecutter ------------------------------ -In this tutorial, we are creating *cookiecutter-website-simple*, a cookiecutter -for generating simple, bare-bones websites. +In this tutorial, we are creating *cookiecutter-website-simple*, a cookiecutter for generating simple, bare-bones websites. Create the directory for your cookiecutter and cd into it: @@ -18,15 +19,13 @@ Create the directory for your cookiecutter and cd into it: Step 2: Create `project_slug` Directory --------------------------------------- -Create a directory called `{{ cookiecutter.project_slug }}`. +Create a directory called ``{{ cookiecutter.project_slug }}``. -This value will be replaced with the repo name of projects that you generate -from this cookiecutter. +This value will be replaced with the repo name of projects that you generate from this cookiecutter. Step 3: Create Files -------------------- -Inside of `{{ cookiecutter.project_slug }}`, create `index.html`, `site.css`, and -`site.js`. +Inside of ``{{ cookiecutter.project_slug }}``, create ``index.html``, ``site.css``, and ``site.js``. To be continued...