Merge pull request #2881 from stevepiercy/docs-cookiecutter-changes-only

docs cookiecutter changes only

docs/conf.py

@@ -64,6 +64,7 @@ def nothing(*arg):
 intersphinx_mapping = {
     'colander': ('http://docs.pylonsproject.org/projects/colander/en/latest', None),
     'cookbook': ('http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/', None),
+    'cookiecutter': ('https://cookiecutter.readthedocs.io/en/latest/', None),
     'deform': ('http://docs.pylonsproject.org/projects/deform/en/latest', None),
     'jinja2': ('http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
     'pylonswebframework': ('http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/', None),

docs/glossary.rst

@@ -1000,6 +1000,10 @@ Glossary
      application and helps users to quickly get started writing larger
      applications.  Scaffolds are usually used via the ``pcreate`` command.
 
+     .. deprecated:: 1.8
+
+     .. seealso:: See also :term:`cookiecutter`.
+
    pyramid_exclog
      A package which logs Pyramid application exception (error) information
      to a standard Python logger.  This add-on is most useful when
@@ -1133,4 +1137,20 @@ Glossary
    Python Packaging Authority
       The `Python Packaging Authority (PyPA) <https://www.pypa.io/en/latest/>`_
       is a working group that maintains many of the relevant projects in Python
-      packaging.
+      packaging.
+
+   cookiecutter
+      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 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>`_
+
+      .. versionadded:: 1.8
+
+      .. seealso:: See also :term:`scaffold`.
+
+   coverage
+      A measurement of code coverage, usually expressed as a percentage of which lines of code have been executed over which lines are executable, typically run during test execution.

docs/tutorials/wiki/authorization.rst

@@ -26,7 +26,7 @@ We will implement the access control with the following steps:
 * Add :term:`permission` declarations to the ``edit_page`` and ``add_page``
   views (``views.py``).
 
-Then we will add the login and logout feature:
+Then we will add the login and logout features:
 
 * Add ``login`` and ``logout`` views (``views.py``).
 * Add a login template (``login.pt``).
@@ -73,7 +73,7 @@ Create a new ``tutorial/security.py`` module with the following content:
 The ``groupfinder`` function accepts a userid and a request and
 returns one of these values:
 
-- If the userid exists in the system, it will return a sequence of group
+- If ``userid`` exists in the system, it will return a sequence of group
   identifiers (or an empty sequence if the user isn't a member of any groups).
 - If the userid *does not* exist in the system, it will return ``None``.
 
@@ -103,19 +103,18 @@ Add an ACL
 ~~~~~~~~~~
 
 Open ``tutorial/models.py`` and add the following import
-statement at the head:
+statement near the top:
 
 .. literalinclude:: src/authorization/tutorial/models.py
-   :lines: 4-7
-   :linenos:
+   :lines: 4-8
+   :lineno-match:
    :language: python
 
 Add the following lines to the ``Wiki`` class:
 
 .. literalinclude:: src/authorization/tutorial/models.py
    :lines: 9-13
-   :linenos:
-   :lineno-start: 9
+   :lineno-match:
    :emphasize-lines: 4-5
    :language: python
 
@@ -124,10 +123,10 @@ permission is allowed, and :data:`~pyramid.security.Everyone`, a special
 :term:`principal` that is associated to all requests.  Both are used in the
 :term:`ACE` entries that make up the ACL.
 
-The ACL is a list that needs to be named `__acl__` and be an attribute of a
+The ACL is a list that needs to be named ``__acl__`` and be an attribute of a
 class.  We define an :term:`ACL` with two :term:`ACE` entries: the first entry
-allows any user the `view` permission.  The second entry allows the
-``group:editors`` principal the `edit` permission.
+allows any user the ``view`` permission.  The second entry allows the
+``group:editors`` principal the ``edit`` permission.
 
 The ``Wiki`` class that contains the ACL is the :term:`resource` constructor
 for the :term:`root` resource, which is a ``Wiki`` instance.  The ACL is
@@ -150,15 +149,14 @@ statements:
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :lines: 1-8
    :linenos:
-   :emphasize-lines: 4-5,8
+   :emphasize-lines: 3-6,8
    :language: python
 
 Now add those policies to the configuration:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :lines: 18-23
-   :linenos:
-   :lineno-start: 18
+   :lineno-match:
    :emphasize-lines: 1-3,5-6
    :language: python
 
@@ -181,12 +179,12 @@ Open ``tutorial/views.py`` and add a ``permission='edit'`` parameter
 to the ``@view_config`` decorators for ``add_page()`` and ``edit_page()``:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 50-52
+   :lines: 49-51
    :emphasize-lines: 2-3
    :language: python
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 70-72
+   :lines: 68-70
    :emphasize-lines: 2-3
    :language: python
 
@@ -235,7 +233,7 @@ Add the following import statements to the head of
 
 .. literalinclude:: src/authorization/tutorial/views.py
    :lines: 6-17
-   :emphasize-lines: 1-12
+   :emphasize-lines: 1-14
    :language: python
 
 All the highlighted lines need to be added or edited.
@@ -248,9 +246,8 @@ cookie.
 Now add the ``login`` and ``logout`` views at the end of the file:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 82-116
-   :linenos:
-   :lineno-start: 82
+   :lines: 80-
+   :lineno-match:
    :language: python
 
 ``login()`` has two decorators:
@@ -287,17 +284,17 @@ the return value of ``view_page()``, ``add_page()``, and ``edit_page()`` as
 follows:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 47-48
+   :lines: 46-47
    :emphasize-lines: 1-2
    :language: python
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 67-68
+   :lines: 65-66
    :emphasize-lines: 1-2
    :language: python
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 78-80
+   :lines: 76-78
    :emphasize-lines: 2-3
    :language: python
 
@@ -314,7 +311,7 @@ Open ``tutorial/templates/edit.pt`` and
 indicated by the highlighted lines.
 
 .. literalinclude:: src/authorization/tutorial/templates/edit.pt
-   :lines: 34-38
+   :lines: 35-39
    :emphasize-lines: 3-5
    :language: html
 
@@ -348,7 +345,7 @@ Our ``tutorial/views.py`` will look like this when we're done:
 
 .. literalinclude:: src/authorization/tutorial/views.py
    :linenos:
-   :emphasize-lines: 8,11-15,17,24,29,48,52,68,72,80,82-120
+   :emphasize-lines: 8,11-15,17,24,29,47,51,66,70,78,80-
    :language: python
 
 Only the highlighted lines need to be added or edited.
@@ -358,7 +355,7 @@ we're done:
 
 .. literalinclude:: src/authorization/tutorial/templates/edit.pt
    :linenos:
-   :emphasize-lines: 36-38
+   :emphasize-lines: 37-39
    :language: html
 
 Only the highlighted lines need to be added or edited.
@@ -368,7 +365,7 @@ we're done:
 
 .. literalinclude:: src/authorization/tutorial/templates/view.pt
    :linenos:
-   :emphasize-lines: 36-38
+   :emphasize-lines: 37-39
    :language: html
 
 Only the highlighted lines need to be added or edited.

docs/tutorials/wiki/background.rst

@@ -13,7 +13,7 @@ Python web framework experience.
 
 To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
-variant, etc.) *or* a Windows system of any kind.
+variant, and so on) *or* a Windows system of any kind.
 
 .. warning::
 

docs/tutorials/wiki/basiclayout.rst

@@ -4,7 +4,7 @@
 Basic Layout
 ============
 
-The starter files generated by the ``zodb`` scaffold are very basic, but
+The starter files generated by the ``zodb`` cookiecutter are very basic, but
 they provide a good orientation for the high-level patterns common to most
 :term:`traversal`-based (and :term:`ZODB`-based) :app:`Pyramid` projects.
 
@@ -44,7 +44,11 @@ Open ``tutorial/__init__.py``.  It should already contain the following:
 #. *Line 15*.  Include support for the :term:`Chameleon` template rendering
    bindings, allowing us to use the ``.pt`` templates.
 
-#. *Line 16*.  Register a "static view", which answers requests whose URL
+#. *Line 16*.  Include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction <https://pypi.python.org/pypi/transaction>`_ package.
+
+#. *Line 17*.  Include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application.
+
+#. *Line 18*.  Register a "static view", which answers requests whose URL
    paths start with ``/static``, using the
    :meth:`pyramid.config.Configurator.add_static_view` method.  This
    statement registers a view that will serve up static assets, such as CSS
@@ -54,19 +58,19 @@ Open ``tutorial/__init__.py``.  It should already contain the following:
    will be ``/static``.  The second argument of this tag is the "path",
    which is a relative :term:`asset specification`, so it finds the resources
    it should serve within the ``static`` directory inside the ``tutorial``
-   package.  Alternatively the scaffold could have used an *absolute* asset
+   package.  Alternatively the cookiecutter could have used an *absolute* asset
    specification as the path (``tutorial:static``).
 
-#. *Line 17*.  Perform a :term:`scan`.  A scan will find :term:`configuration
+#. *Line 19*.  Perform a :term:`scan`.  A scan will find :term:`configuration
    decoration`, such as view configuration decorators (e.g., ``@view_config``)
    in the source code of the ``tutorial`` package and will take actions based
    on these decorators.  We don't pass any arguments to
    :meth:`~pyramid.config.Configurator.scan`, which implies that the scan
    should take place in the current package (in this case, ``tutorial``).
-   The scaffold could have equivalently said ``config.scan('tutorial')``, but
+   The cookiecutter could have equivalently said ``config.scan('tutorial')``, but
    it chose to omit the package name argument.
 
-#. *Line 18*.  Use the
+#. *Line 20*.  Use the
    :meth:`pyramid.config.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
@@ -79,7 +83,7 @@ hierarchically in a :term:`resource tree`.  This tree is consulted by
 tree represents the site structure, but it *also* represents the
 :term:`domain model` of the application, because each resource is a node
 stored persistently in a :term:`ZODB` database.  The ``models.py`` file is
-where the ``zodb`` scaffold put the classes that implement our
+where the ``zodb`` cookiecutter put the classes that implement our
 resource objects, each of which also happens to be a domain model object.
 
 Here is the source for ``models.py``:
@@ -93,7 +97,7 @@ Here is the source for ``models.py``:
    because the class inherits from the
    :class:`persistent.mapping.PersistentMapping` class.  The ``__parent__``
    and ``__name__`` are important parts of the :term:`traversal` protocol.
-   By default, have these as ``None`` indicating that this is the
+   By default, set these to ``None`` to indicate that this is the
    :term:`root` object.
 
 #. *Lines 8-14*.  ``appmaker`` is used to return the *application
@@ -110,7 +114,7 @@ Here is the source for ``models.py``:
 Views With ``views.py``
 -----------------------
 
-Our scaffold generated a default ``views.py`` on our behalf.  It
+Our cookiecutter generated a default ``views.py`` on our behalf.  It
 contains a single view, which is used to render the page shown when you visit
 the URL ``http://localhost:6543/``.
 
@@ -156,7 +160,7 @@ Let's try to understand the components in this module:
 
 #. *Lines 6-7*.  We define a :term:`view callable` named ``my_view``, which
    we decorated in the step above.  This view callable is a *function* we
-   write generated by the ``zodb`` scaffold that is given a
+   write generated by the ``zodb`` cookiecutter that is given a
    ``request`` and which returns a dictionary.  The ``mytemplate.pt``
    :term:`renderer` named by the asset specification in the step above will
    convert this dictionary to a :term:`response` on our behalf.
@@ -168,8 +172,8 @@ Let's try to understand the components in this module:
 Configuration in ``development.ini``
 ------------------------------------
 
-The ``development.ini`` (in the tutorial :term:`project` directory, as
-opposed to the tutorial :term:`package` directory) looks like this:
+The ``development.ini`` (in the ``tutorial`` :term:`project` directory, as
+opposed to the ``tutorial`` :term:`package` directory) looks like this:
 
 .. literalinclude:: src/basiclayout/development.ini
   :language: ini

docs/tutorials/wiki/definingmodels.rst

@@ -4,7 +4,7 @@
 Defining the Domain Model
 =========================
 
-The first change we'll make to our stock ``pcreate``-generated application will
+The first change we'll make to our stock cookiecutter-generated application will
 be to define two :term:`resource` constructors, one representing a wiki page,
 and another representing the wiki as a mapping of wiki page names to page
 objects.  We'll do this inside our ``models.py`` file.
@@ -50,7 +50,9 @@ The first thing we want to do is remove the ``MyModel`` class from the
 generated ``models.py`` file.  The ``MyModel`` class is only a sample and
 we're not going to use it.
 
-Then, we'll add a ``Wiki`` class.  We want it to inherit from the
+Then we'll add an import at the top for the :class:`persistent.Persistent` class.  We'll use this for a new ``Page`` class in a moment.
+
+Then we'll add a ``Wiki`` class.  We want it to inherit from the
 :class:`persistent.mapping.PersistentMapping` class because it provides
 mapping behavior, and it makes sure that our Wiki page is stored as a
 "first-class" persistent object in our ZODB database.