From 6261ae4fbf73cb9e72aea2b8f67c6b04e5c474a6 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Mon, 26 Dec 2016 23:59:14 -0800
Subject: narr/cookiecutters - add narr/scaffolding - update index - add link
 to narr/cookiecutters

---
 docs/index.rst              |  1 +
 docs/narr/cookiecutters.rst | 20 ++++++++++++++++++++
 docs/narr/scaffolding.rst   |  4 ++++
 3 files changed, 25 insertions(+)
 create mode 100644 docs/narr/cookiecutters.rst

diff --git a/docs/index.rst b/docs/index.rst
index 60dcdcc9c..668347744 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -145,6 +145,7 @@ Narrative documentation in chapter form explaining how to use :app:`Pyramid`.
    narr/extending
    narr/advconfig
    narr/extconfig
+   narr/cookiecutters
    narr/scaffolding
    narr/upgrading
    narr/threadlocals
diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst
new file mode 100644
index 000000000..bb4c61616
--- /dev/null
+++ b/docs/narr/cookiecutters.rst
@@ -0,0 +1,20 @@
+.. _cookiecutters:
+
+Pyramid cookiecutters
+=====================
+
+.. versionadded:: 1.8
+
+A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates), e.g., creating a Python package project from a Python package project template.
+
+Pyramid cookiecutters have replaced the now deprecated Pyramid scaffolds, and should be used going forward. Pyramid cookiecutters released under the Pylons Project include:
+
+* `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_
+* `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
+* `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_
+
+Development of cookiecutters is documented under `Learn the Basics of Cookiecutter by Creating a Cookiecutter <https://cookiecutter.readthedocs.io/en/latest/first_steps.html>`_.
+
+.. seealso:: See also `Cookiecutter Features <https://cookiecutter.readthedocs.io/en/latest/readme.html#features>`_.
+
+.. seealso:: See also :term:`scaffold`.
diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst
index 164ceb3bf..27239d34e 100644
--- a/docs/narr/scaffolding.rst
+++ b/docs/narr/scaffolding.rst
@@ -3,6 +3,10 @@
 Creating Pyramid Scaffolds
 ==========================
 
+.. deprecated:: 1.8
+
+    Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutters` instead.
+
 You can extend Pyramid by creating a :term:`scaffold` template.  A scaffold
 template is useful if you'd like to distribute a customizable configuration of
 Pyramid to other users.  Once you've created a scaffold, and someone has
-- 
cgit v1.2.3