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.