Docs cookiecutter changes only - Quick Tutorial and all other files

docs/designdefense.rst

@@ -591,7 +591,7 @@ extensibility because it must be deployed in multiple locations.
 Pyramid Is Too Big
 ------------------
 
-"The :app:`Pyramid` compressed tarball is larger than 2MB.  It must beenormous!"
+"The :app:`Pyramid` compressed tarball is larger than 2MB.  It must be enormous!"
 
 No.  We just ship it with docs, test code, and scaffolding.  Here's a breakdown
 of what's included in subdirectories of the package tree:

docs/glossary.rst

@@ -992,7 +992,7 @@ Glossary
      pages rendered by your application, displaying request, routing, and
      database information.  :mod:`pyramid_debugtoolbar` is configured into
      the ``development.ini`` of all applications which use a Pyramid
-     :term:`scaffold`.  For more information, see
+     :term:`cookiecutter`.  For more information, see
      http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/.
 
    scaffold
@@ -1063,7 +1063,7 @@ Glossary
 
    Waitress
       A :term:`WSGI` server that runs on UNIX and Windows under Python 2.6+
-      and Python 3.2+.  Projects generated via Pyramid scaffolding use
+      and Python 3.2+.  Projects generated via Pyramid cookiecutters use
       Waitress as a WGSI server.  See
       http://docs.pylonsproject.org/projects/waitress/en/latest/ for detailed
       information.

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

docs/latexindex.rst

@@ -78,6 +78,7 @@ Narrative Documentation
    narr/extending
    narr/advconfig
    narr/extconfig
+   narr/cookiecutters
    narr/scaffolding
    narr/upgrading
    narr/threadlocals

docs/narr/assets.rst

@@ -28,7 +28,7 @@ asset:
 
 The use of assets is quite common in most web development projects.  For
 example, when you create a :app:`Pyramid` application using one of the
-available scaffolds, as described in :ref:`creating_a_project`, the directory
+available :term:`cookiecutter`\ s, as described in :ref:`creating_a_project`, the directory
 representing the application contains a Python :term:`package`. Within that
 Python package, there are directories full of files which are static assets.
 For example, there's a ``static`` directory which contains ``.css``, ``.js``,

docs/narr/commandline.rst

@@ -839,7 +839,7 @@ In general, you can make your script into a console script by doing the
 following:
 
 - Use an existing distribution (such as one you've already created via
-  ``pcreate``) or create a new distribution that possesses at least one package
+  ``cookiecutter``) or create a new distribution that possesses at least one package
   or module.  It should, within any module within the distribution, house a
   callable (usually a function) that takes no arguments and which runs any of
   the code you wish to run.

docs/narr/cookiecutters.rst

@@ -0,0 +1,22 @@
+.. _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>`_
+
+.. 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>`_.
+
+.. seealso::
+
+    See also :term:`scaffold`.

docs/narr/extending.rst

@@ -190,7 +190,7 @@ The general pattern for extending an existing application looks something like
 this:
 
 - Create a new Python package.  The easiest way to do this is to create a new
-  :app:`Pyramid` application using the scaffold mechanism.  See
+  :app:`Pyramid` application using a :term:`cookiecutter`.  See
   :ref:`creating_a_project` for more information.
 
 - In the new package, create Python files containing views and other overridden

docs/narr/install.rst

@@ -260,5 +260,5 @@ What Gets Installed
 When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy,
 and others are installed.
 
-Additionally, as chronicled in :ref:`project_narr`, scaffolds will be
-registered, which make it easy to start a new :app:`Pyramid` project.
+Additionally, as chronicled in :ref:`project_narr`, :term:`cookiecutter`\ s will be
+used, which make it easy to start a new :app:`Pyramid` project.

docs/narr/introduction.rst

@@ -182,7 +182,7 @@ available. Pyramid can automatically utilize changed templates when rendering
 pages and automatically restart the application to incorporate changed Python
 code. Plain old ``print()`` calls used for debugging can display to a console.
 
-Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to
+Pyramid's debug toolbar comes activated when you use a Pyramid :term:`cookiecutter` to
 render a project.  This toolbar overlays your application in the browser, and
 allows you access to framework data, such as the routes configured, the last
 renderings performed, the current set of packages installed, SQLAlchemy queries
@@ -494,7 +494,7 @@ Example: :ref:`view_configuration_parameters`.
 Transaction management
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Pyramid's :term:`scaffold` system renders projects that include a *transaction
+A couple of Pyramid's :term:`cookiecutter`\ s include a *transaction
 management* system, stolen from Zope.  When you use this transaction management
 system, you cease being responsible for committing your data anymore.  Instead
 Pyramid takes care of committing: it commits at the end of a request or aborts

docs/narr/logging.rst

@@ -9,11 +9,11 @@ to send log messages to loggers that you've configured.
 
 .. warning::
 
-   This chapter assumes you've used a :term:`scaffold` to create a project
+   This chapter assumes you've used a :term:`cookiecutter` to create a project
    which contains ``development.ini`` and ``production.ini`` files which help
-   configure logging.  All of the scaffolds which ship with :app:`Pyramid` do
-   this.  If you're not using a scaffold, or if you've used a third-party
-   scaffold which does not create these files, the configuration information in
+   configure logging.  All of the Pyramid cookiecutters provided by the Pylons Project do
+   this.  If you're not using a cookiecutter, or if you've used a third-party
+   cookiecutter which does not create these files, the configuration information in
    this chapter may not be applicable.
 
 .. index:
@@ -26,11 +26,11 @@ to send log messages to loggers that you've configured.
 Logging Configuration
 ---------------------
 
-A :app:`Pyramid` project created from a :term:`scaffold` is configured to allow
+A :app:`Pyramid` project created from a :term:`cookiecutter` is configured to allow
 you to send messages to :mod:`Python standard library logging package
 <logging>` loggers from within your application.  In particular, the
 :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created
-when you use a scaffold include a basic configuration for the Python
+when you use a cookiecutter include a basic configuration for the Python
 :mod:`logging` package.
 
 PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser
@@ -43,94 +43,20 @@ from when you run ``pserve``.
 The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function,
 a thin wrapper around the :func:`logging.config.fileConfig` using the specified
 ``.ini`` file, if it contains a ``[loggers]`` section (all of the
-scaffold-generated ``.ini`` files do). ``setup_logging`` reads the logging
+cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging
 configuration from the ini file upon which ``pserve`` was invoked.
 
 Default logging configuration is provided in both the default
-``development.ini`` and the ``production.ini`` file.  The logging configuration
+``development.ini`` and the ``production.ini`` files.  If you use ``pyramid-cookiecutter-starter`` to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration
 in the ``development.ini`` file is as follows:
 
-.. code-block:: ini
-   :linenos:
-
-   # Begin logging configuration
-
-   [loggers]
-   keys = root, {{package_logger}}
-
-   [handlers]
-   keys = console
-
-   [formatters]
-   keys = generic
-
-   [logger_root]
-   level = INFO
-   handlers = console
-
-   [logger_{{package_logger}}]
-   level = DEBUG
-   handlers =
-   qualname = {{package}}
-
-   [handler_console]
-   class = StreamHandler
-   args = (sys.stderr,)
-   level = NOTSET
-   formatter = generic
-
-   [formatter_generic]
-   format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-   # End logging configuration
+.. literalinclude:: myproject/development.ini
+    :language: ini
+    :lineno-match:
+    :lines: 29-
 
 The ``production.ini`` file uses the ``WARN`` level in its logger
-configuration, but it is otherwise identical.
-
-The name ``{{package_logger}}`` above will be replaced with the name of your
-project's :term:`package`, which is derived from the name you provide to your
-project.  For instance, if you do:
-
-.. code-block:: text
-   :linenos:
-
-   pcreate -s starter MyApp
-
-The logging configuration will literally be:
-
-.. code-block:: ini
-   :linenos:
-
-   # Begin logging configuration
-
-   [loggers]
-   keys = root, myapp
-
-   [handlers]
-   keys = console
-
-   [formatters]
-   keys = generic
-
-   [logger_root]
-   level = INFO
-   handlers = console
-
-   [logger_myapp]
-   level = DEBUG
-   handlers =
-   qualname = myapp
-
-   [handler_console]
-   class = StreamHandler
-   args = (sys.stderr,)
-   level = NOTSET
-   formatter = generic
-
-   [formatter_generic]
-   format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-   # End logging configuration
+configuration instead of ``DEBUG``, but it is otherwise identical.
 
 In this logging configuration:
 
@@ -149,7 +75,7 @@ that ask for a logger (via ``logging.getLogger``) that has a name which begins
 with anything except your project's package name (e.g., ``myapp``). The logger
 with the same name as your package name is reserved for your own usage in your
 :app:`Pyramid` application.  Its existence means that you can log to a known
-logging location from any :app:`Pyramid` application generated via a scaffold.
+logging location from any :app:`Pyramid` application generated via a cookiecutter.
 
 :app:`Pyramid` and many other libraries (such as Beaker, SQLAlchemy, Paste) log
 a number of messages to the root logger for debugging purposes. Switching the
@@ -162,9 +88,9 @@ root logger level to ``DEBUG`` reveals them:
     level = DEBUG
     handlers = console
 
-Some scaffolds configure additional loggers for additional subsystems they use
+Some cookiecutters configure additional loggers for additional subsystems they use
 (such as SQLALchemy).  Take a look at the ``production.ini`` and
-``development.ini`` files rendered when you create a project from a scaffold.
+``development.ini`` files rendered when you create a project from a cookiecutter.
 
 Sending Logging Messages
 ------------------------
@@ -327,14 +253,14 @@ translogger and your application in it.  For instance, change from this:
 .. code-block:: ini
 
     [app:main]
-    use = egg:MyProject
+    use = egg:myproject
 
 To this:
 
 .. code-block:: ini
 
     [app:mypyramidapp]
-    use = egg:MyProject
+    use = egg:myproject
 
     [filter:translogger]
     use = egg:Paste#translogger

docs/narr/myproject/.coveragerc

@@ -0,0 +1,3 @@
+[run]
+source = myproject
+omit = myproject/test*

docs/narr/myproject/CHANGES.txt

@@ -0,0 +1,4 @@
+0.0
+---
+
+- Initial version.

docs/narr/MyProject/MANIFEST.in → docs/narr/myproject/MANIFEST.in

@@ -1,2 +1,2 @@
 include *.txt *.ini *.cfg *.rst
-recursive-include myproject *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml
+recursive-include myproject *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml *.jinja2

docs/narr/myproject/README.txt

@@ -0,0 +1,29 @@
+MyProject
+===============================
+
+Getting Started
+---------------
+
+- Change directory into your newly created project.
+
+    cd MyProject
+
+- Create a Python virtual environment.
+
+    python3 -m venv env
+
+- Upgrade packaging tools.
+
+    env/bin/pip install --upgrade pip setuptools
+
+- Install the project in editable mode with its testing requirements.
+
+    env/bin/pip install -e ".[testing]"
+
+- Run your project's tests.
+
+    env/bin/pytest
+
+- Run your project.
+
+    env/bin/pserve development.ini