From 7c7e7eca7c58fa8319e57db582b33f0452df47f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 25 Dec 2019 02:41:52 -0800 Subject: Expand cookiecutters doc to include more references, using the old scaffolds.rst as an example. - Update reST target and label for Pyramid cookiecutters. --- docs/narr/cookiecutters.rst | 29 ++++++++++++++++++++++++----- docs/narr/project.rst | 2 +- 2 files changed, 25 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index 066d6c2e5..3642f38fa 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -1,11 +1,20 @@ -.. _cookiecutters: +.. index:: + single: cookiecutter + +.. _pyramid-cookiecutters: Pyramid cookiecutters ===================== -A :term:`cookiecutter` is a command-line utility that creates projects from `cookiecutters `__ (project templates). +A :term:`cookiecutter` is a command-line utility that creates projects from `cookiecutters `_ (project templates). + +The Pylons Project supports one official Pyramid cookiecutter `pyramid-cookiecutter-starter `_. -`pyramid-cookiecutter-starter `_ +Cookiecutters that use Pyramid can be found using a `search of the GitHub topic "cookiecutter-template" for "Pyramid" `_. + +You can extend Pyramid by creating a :term:`cookiecutter` project template. +This is useful if you would like to distribute a customizable configuration of Pyramid to other users. +Once you have created a cookiecutter, other people can use it to create a custom version of your Pyramid application. .. versionadded:: 1.8 Added cookiecutter support. @@ -17,6 +26,16 @@ A :term:`cookiecutter` is a command-line utility that creates projects from `coo ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported. Use ``pyramid-cookiecutter-starter`` going forward. -.. seealso:: - See also `Cookiecutter Installation `_ and `Cookiecutter Features `_. Development of cookiecutters is documented under `Learn the Basics of Cookiecutter by Creating a Cookiecutter `_. +.. _cookiecutter-basics: + +Basics +------ + +See `Cookiecutter Installation `_ to get started. + +Then see the `README `_ of ``pyramid-cookiecutter-starter`` for its usage to generate a starter project. + +The ``pyramid-cookiecutter-starter`` on its ``master`` branch is a good starting point to develop your own cookiecutter. +Development of cookiecutters is documented under `Learn the Basics of Cookiecutter by Creating a Cookiecutter `_. +See `Cookiecutter Features `_ for details of what is possible. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 58bef5701..5edef3435 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -73,7 +73,7 @@ In :ref:`installing_chapter`, you created a virtual Python environment via the ``venv`` command. We called the virtual environment directory ``env`` and set an environment variable ``VENV`` to its path. -We assume that you :ref:`previously installed cookiecutter `, following its installation instructions. +We assume that you :ref:`previously installed cookiecutter `, following its installation instructions. When we invoke ``cookiecutter``, it will create a directory that represents our project. -- cgit v1.2.3 From 582272a881b1896cfe33c0b6bb813115d63b21fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 25 Dec 2019 02:59:32 -0800 Subject: Fix broken reference to pyramid-cookiecutters --- docs/quick_tutorial/ini.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 0bb7da1ba..d2bce0de8 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -133,7 +133,7 @@ Extra credit .. seealso:: :ref:`project_narr`, - :ref:`cookiecutters`, + :ref:`pyramid-cookiecutters`, :ref:`what_is_this_pserve_thing`, :ref:`environment_chapter`, :ref:`paste_chapter` -- cgit v1.2.3 From 41ce5820b01c6e7d14654bb5fbd837611aad5853 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Dec 2019 01:09:33 -0800 Subject: Avoid "WARNING: Duplicate explicit target name" errors by using a double underscore to make an anonymous hyperlink. See: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks - Restore previous reference names in other doc files. --- docs/narr/cookiecutters.rst | 4 ++-- docs/narr/project.rst | 2 +- docs/quick_tutorial/ini.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index 3642f38fa..bb60c2226 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -1,12 +1,12 @@ .. index:: single: cookiecutter -.. _pyramid-cookiecutters: +.. _cookiecutters: Pyramid cookiecutters ===================== -A :term:`cookiecutter` is a command-line utility that creates projects from `cookiecutters `_ (project templates). +A :term:`cookiecutter` is a command-line utility that creates projects from `cookiecutters `__ (project templates). The Pylons Project supports one official Pyramid cookiecutter `pyramid-cookiecutter-starter `_. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5edef3435..58bef5701 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -73,7 +73,7 @@ In :ref:`installing_chapter`, you created a virtual Python environment via the ``venv`` command. We called the virtual environment directory ``env`` and set an environment variable ``VENV`` to its path. -We assume that you :ref:`previously installed cookiecutter `, following its installation instructions. +We assume that you :ref:`previously installed cookiecutter `, following its installation instructions. When we invoke ``cookiecutter``, it will create a directory that represents our project. diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index d2bce0de8..0bb7da1ba 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -133,7 +133,7 @@ Extra credit .. seealso:: :ref:`project_narr`, - :ref:`pyramid-cookiecutters`, + :ref:`cookiecutters`, :ref:`what_is_this_pserve_thing`, :ref:`environment_chapter`, :ref:`paste_chapter` -- cgit v1.2.3