From 7c7e7eca7c58fa8319e57db582b33f0452df47f7 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
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 <https://cookiecutter.readthedocs.io/en/latest/>`__ (project templates).
+A :term:`cookiecutter` is a command-line utility that creates projects from `cookiecutters <https://cookiecutter.readthedocs.io/en/latest/>`_ (project templates).
+
+The Pylons Project supports one official Pyramid cookiecutter `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_.
 
-`pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
+Cookiecutters that use Pyramid can be found using a `search of the GitHub topic "cookiecutter-template" for "Pyramid" <https://github.com/topics/cookiecutter-template?q=pyramid&unscoped_q=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 <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ and `Cookiecutter Features <https://cookiecutter.readthedocs.io/en/latest/readme.html#features>`_. Development of cookiecutters is documented under `Learn the Basics of Cookiecutter by Creating a Cookiecutter <https://cookiecutter.readthedocs.io/en/latest/first_steps.html>`_.
+.. _cookiecutter-basics:
+
+Basics
+------
+
+See `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ to get started.
+
+Then see the `README <https://github.com/Pylons/pyramid-cookiecutter-starter#pyramid-cookiecutter-starter>`_ 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 <https://cookiecutter.readthedocs.io/en/latest/first_steps.html>`_.
+See `Cookiecutter Features <https://cookiecutter.readthedocs.io/en/latest/README.html#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 <cookiecutters>`, following its installation instructions.
+We assume that you :ref:`previously installed cookiecutter <pyramid-cookiecutters>`, following its installation instructions.
 
 When we invoke ``cookiecutter``, it will create a directory that represents our project.
 
-- 
cgit v1.2.3