Documentation overhaul

AUTHORS.md

@@ -169,6 +169,7 @@
 - Tom Forbes ([@orf](https://github.com/orf))
 - Xie Yanbo ([@xyb](https://github.com/xyb))
 - Maxim Ivanov ([@ivanovmg](https://github.com/ivanovmg))
+- Jens Klein ([@jensens](https://github.com/jensens))
 
 ## Backers
 

CODE_OF_CONDUCT.md

@@ -1,5 +1,4 @@
 # Code of Conduct
 
-Everyone interacting in the Cookiecutter project's codebases, issue trackers,
-chat rooms, and mailing lists is expected to follow the
-[PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/).
+Everyone interacting in the Cookiecutter project's codebases and documentation is expected to follow the [PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/).
+This includes, but is not limited to, issue trackers, chat rooms, mailing lists, and other virtual or in real life communication.

HISTORY.md

@@ -4,10 +4,15 @@ History is important, but our current roadmap can be found [here](https://github
 
 ## 2.0.2 (2021-12-27)
 
+*Remark: This release never made it to official PyPI*
+
 * Fix Python version number in cookiecutter --version and test on Python 3.10 (#1621) @ozer550
 * Removed changes related to setuptools_scm (#1629) @audreyfeldroy @ozer550
 
 ## 2.0.1 (2021-12-11)
+
+*Remark: This release never made it to official PyPI*
+
 ### Breaking Changes
 
 * Release preparation for 2.0.1rc1 (#1608) @audreyfeldroy
@@ -105,7 +110,7 @@ History is important, but our current roadmap can be found [here](https://github
 ## 1.7.1 (2020-04-21)
 
 This release was focused on internal code and CI/CD changes. During this release
-all code was verified to match pep8, pep257 and other code-styling guides.  
+all code was verified to match pep8, pep257 and other code-styling guides.
 Project CI/CD was significantly changed, Windows platform checks based on Appveyor
 engine was replaced by GitHub actions tests. Appveyor was removed. Also our
 CI/CD was extended with Mac builds, to verify project builds on Apple devices.
@@ -773,7 +778,7 @@ Other changes:
     $ cookiecutter cookiecutter-pypackage/
     # Create project from the cookiecutter-pypackage.git repo template
     $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git
-```  
+```
 
 * Can now use Cookiecutter from Python as a package:
 

Makefile

@@ -63,6 +63,10 @@ docs: ## Generate Sphinx HTML documentation, including API docs
 	@rm -f docs/cookiecutter.rst
 	@sphinx-apidoc -o docs/ cookiecutter
 	@rm -f docs/modules.rst
+	@sed -i 's/cookiecutter package/===\nAPI\n===/' docs/cookiecutter.rst
+	@sed -i 's/====================//' docs/cookiecutter.rst
+	@sed -i 's/Submodules/This is the Cookiecutter modules API documentation./' docs/cookiecutter.rst
+	@sed -i 's/^----------$$//' docs/cookiecutter.rst
 	@$(MAKE) -C docs clean
 	@$(MAKE) -C docs html
 	@$(BROWSER) docs/_build/html/index.html

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/index.rst

@@ -17,7 +17,6 @@ Various advanced topics regarding cookiecutter usage.
    private_variables
    copy_without_render
    replay
-   cli_options
    choice_variables
    dict_variables
    template_extensions