Documentation overhaul (3)

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 <apiref>` for more details.

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 <https://jinja.palletsprojects.com/en/latest/templates/#if>`_ 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"]

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.

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 %}
     <dl>

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"

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
-<https://docs.python.org/3/library/sys.html#sys.exit>`_), 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 <https://docs.python.org/3/library/sys.html#sys.exit>`_), 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
 

docs/advanced/injecting_context.rst

@@ -3,25 +3,40 @@
 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 }}"
     }
 
 
 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.

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
 

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",