doc fixes

Stephen Martin

2018-09-17 f2520e5910861beac0199aa424ba282f856f79b3

doc fixes

 docs/narr/advanced-features.rst

@@ -51,7 +51,7 @@
Stop Worrying About Transactions
--------------------------------

:app:`Pyramid`\ 's :term:`cookiecutter`\ renders projects that include a *transaction management* system.  When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception.
:app:`Pyramid`\ 's :term:`cookiecutter` renders projects that include a *transaction management* system.  When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception.

Why is that a good thing? Imagine a situation where you manually commit a change to your persistence layer. It's very likely that other framework code will run *after* your changes are done. If an error happens in that other code, you can easily wind up with inconsistent data if you're not extremely careful.


 docs/narr/assets.rst

@@ -27,7 +27,7 @@
  package.

The use of assets is quite common in most web development projects.  For
example, when you create a :app:`Pyramid` application using our
example, when you create a :app:`Pyramid` application using the
:term:`cookiecutter`, 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.

 docs/narr/commandline.rst

@@ -298,7 +298,7 @@
        # start a transaction which can be used in the shell
        request.tm.begin()

        # if using the alchemy backend to our cookiecutter, the dbsession is
        # if using the SQLAlchemy backend from our cookiecutter, the dbsession is
        # connected to the transaction manager above
        env['tm'] = request.tm
        env['dbsession'] = request.dbsession

 docs/narr/cookiecutters.rst

@@ -3,10 +3,12 @@
Pyramid cookiecutters
=====================

.. versionadded:: 1.8
.. versionadded:: 1.10

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.

The unified cookiecutter ``pyramid-cookiecutter-theonecc`` merged features from the three previous cookiecutters which are now deprecated.

The Pyramid cookiecutter has replaced the now deprecated Pyramid scaffolds, and should be used going forward and can be found here:

* `pyramid-cookiecutter-theonecc <https://github.com/Pylons/pyramid-cookiecutter-theonecc>`_

 docs/narr/install.rst

@@ -262,4 +262,4 @@
When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy,
and others are installed.

Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which make it easy to start a new :app:`Pyramid` project.
Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which makes it easy to start a new :app:`Pyramid` project.

 docs/narr/logging.rst

@@ -89,7 +89,7 @@
    handlers = console

Some configurations of the :app:`Pyramid` cookiecutter configure additional loggers for
additional subsystems they use (such as SQLALchemy).  Take a look at the
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 our cookiecutter.


 docs/narr/project.rst

@@ -17,7 +17,7 @@

The Pylons Project provides a :app:`Pyramid` cookiecutter that you can use to
generate a project.  Our cookiecutter allows several configuration options
to layout what type of application you're trying to construct.
to generate the type of application you're trying to construct.

This cookiecutter is rendered using the ``cookiecutter`` command that you may install.

@@ -35,25 +35,27 @@
:app:`Pyramid` cookiecutters
----------------------------

The Pyramid cookiecutter released under the Pylons Project differ in configuration options on a number of axes:
The Pyramid cookiecutter released under the Pylons Project offers the following configuration options:

- the persistence mechanism it offers (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`)
- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`)

- the mechanism it uses to map URLs to code (:term:`URL dispatch` or :term:`traversal`)
- the persistence mechanism (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`)

- All include an option of templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`)
- the mechanism of mapping URLs to code (:term:`URL dispatch` or :term:`traversal`)

* `pyramid-cookiecutter-theonecc <https://github.com/Pylons/pyramid-cookiecutter-theonecc>`_

These configurations include:
All configuration options offer a choice of templating language.

``no persistance``
The configuration of mapping URLs to code (routing) depends on the backend option selected, with additional variations as follows.

``none``
    :term:`URL dispatch` for routing

``SQLAlchemy``
    SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, and :term:`URL dispatch` for routing
``sqlalchemy``
    SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Alembic` for database migrations

``ZODB``
``zodb``
    :term:`ZODB` for persistent storage and :term:`traversal` for routing



 docs/quick_tutorial/cookiecutters.rst

@@ -4,7 +4,7 @@
Prelude: Quick Project Startup with Cookiecutters
=================================================

To ease the process of getting started on a project, the Pylons Project provides :term:`cookiecutter`\ s that generate sample :app:`Pyramid` projects from project templates. These cookiecutters will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``.
To ease the process of getting started on a project, the Pylons Project provides a :term:`cookiecutter` that generates sample :app:`Pyramid` projects from project templates. The cookiecutter will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``.


Objectives
@@ -61,17 +61,6 @@
        env/bin/pip install --upgrade pip setuptools
        # ...and into which we install our project.
        env/bin/pip install -e .

    **Note:** If you selected ``sqlalchemy`` in the preceding step, continue. Otherwise, skip to the next step.

    .. code-block:: bash

    # Generate your first revision.
    env/bin/alembic -c development.ini revision --autogenerate -m "init"
    # Upgrade to that revision.
    env/bin/alembic -c development.ini upgrade head
    # Load default data.
    env/bin/initialize_cc_starter_db development.ini

#.  Start up the application by pointing :app:`Pyramid`'s ``pserve`` command at the
    project's (generated) configuration file:

 docs/quick_tutorial/databases.rst

@@ -21,10 +21,10 @@

.. note::

    The Pyramid cookiecutter is really helpful for getting an SQLAlchemy
    project going, including generation of the console script. Since we want to
    see all the decisions, we will forgo convenience in this tutorial, and wire
    it up ourselves.
    The Pyramid cookiecutter ``pyramid-cookiecutter-theonecc`` is really
    helpful for getting a SQLAlchemy project going, including generation of
    the console script. Since we want to see all the decisions, we will forgo
    convenience in this tutorial, and wire it up ourselves.


Objectives

 docs/tutorials/wiki/basiclayout.rst

@@ -4,10 +4,10 @@
Basic Layout
============

The starter files generated by the ``zodb`` backend 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.
The starter files generated by selecting the ``zodb`` backend in the
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.


Application configuration with ``__init__.py``

 docs/tutorials/wiki/definingviews.rst

@@ -99,8 +99,8 @@
We added some imports and created a regular expression to find "WikiWords".

We got rid of the ``my_view`` view function and its decorator that was added
when we originally rendered the ``zodb`` backend cookiecutter.  It was only an example and
isn't relevant to our application.
when originally rendered after we selected the ``zodb`` backend option in the
cookiecutter.  It was only an example and isn't relevant to our application.

Then we added four :term:`view callable` functions to our ``views.py``
module:

 docs/tutorials/wiki/installation.rst

@@ -365,11 +365,10 @@
application while you develop.


Decisions the ``zodb`` backend cookiecutter has made for you
------------------------------------------------------------
Decisions the cookiecutter backend option ``zodb`` has made for you
-------------------------------------------------------------------

Creating a project using the ``zodb`` backend cookiecutter makes the following
assumptions:
When creating a project and selecting the backend option of ``zodb``, the cookiecutter makes the following assumptions:

- You are willing to use :term:`ZODB` for persistent storage.


 docs/tutorials/wiki/tests.rst

@@ -16,7 +16,7 @@
we'll write a test class for the ``appmaker``.

To do so, we'll retain the ``tutorial.tests.ViewTests`` class that was
generated as part of the ``zodb`` backend cookiecutter.  We'll add three test
generated from choosing the ``zodb`` backend option.  We'll add three test
classes: one for the ``Page`` model named ``PageModelTests``, one for the
``Wiki`` model named ``WikiModelTests``, and one for the appmaker named
``AppmakerTests``.
@@ -26,7 +26,7 @@

We'll modify our ``tests.py`` file, adding tests for each view function we
added previously.  As a result, we'll delete the ``ViewTests`` class that the
``zodb`` backend cookiecutter provided, and add four other test classes:
``zodb`` backend option provided, and add four other test classes:
``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and ``EditPageTests``.
These test the ``view_wiki``, ``view_page``, ``add_page``, and ``edit_page``
views.

 docs/tutorials/wiki2/basiclayout.rst

@@ -4,9 +4,10 @@
Basic Layout
============

The starter files generated by the ``sqlalchemy`` backend cookiecutter are very
basic, but they provide a good orientation for the high-level patterns common
to most :term:`URL dispatch`-based :app:`Pyramid` projects.
The starter files generated from choosing the ``sqlalchemy`` backend option in
the cookiecutter are very basic, but they provide a good orientation for the
high-level patterns common to most :term:`URL dispatch`-based :app:`Pyramid`
projects.


Application configuration with ``__init__.py``

 docs/tutorials/wiki2/definingviews.rst

@@ -133,9 +133,9 @@
We added some imports, and created a regular expression to find "WikiWords".

We got rid of the ``my_view`` view function and its decorator that was added
when we originally rendered the ``sqlalchemy`` backend cookiecutter.  It was
only an example and isn't relevant to our application.  We also deleted the
``db_err_msg`` string.
when originally rendered after we selected the ``sqlalchemy`` backend option in
the cookiecutter.  It was only an example and isn't relevant to our
application.  We also deleted the ``db_err_msg`` string.

Then we added four :term:`view callable` functions to our ``views/default.py``
module, as mentioned in the previous step:
@@ -436,8 +436,8 @@
  the view.

Finally, we may delete the ``tutorial/templates/mytemplate.jinja2`` template
that was provided by the ``sqlalchemy`` backend cookiecutter, as we have
created our own templates for the wiki.
that was provided by selecting the backend option of ``sqlalchemy``, as we
have created our own templates for the wiki.

.. note::


 docs/tutorials/wiki2/installation.rst

@@ -519,11 +519,11 @@
application while you develop.


Decisions the ``sqlalchemy`` backend cookiecutter has made for you
------------------------------------------------------------------
Decisions the cookiecutter backend option ``sqlalchemy`` has made for you
-------------------------------------------------------------------------

Creating a project using the ``sqlalchemy`` cookiecutter makes the following
assumptions:
When creating a project and selecting the backend option of ``sqlalchemy``, the
cookiecutter makes the following assumptions:

- You are willing to use SQLite for persistent storage, although almost any SQL database could be used with SQLAlchemy.


 docs/tutorials/wiki2/tests.rst

@@ -8,8 +8,8 @@
tests in a new ``tests`` subpackage.  Tests ensure that an application works,
and that it continues to work when changes are made in the future.

The file ``tests.py`` was generated as part of the ``sqlalchemy`` backend
cookiecutter, but it is a common practice to put tests into a ``tests``
The file ``tests.py`` was generated from choosing the ``sqlalchemy`` backend
option, but it is a common practice to put tests into a ``tests``
subpackage, especially as projects grow in size and complexity.  Each module in
the test subpackage should contain tests for its corresponding module in our
application.  Each corresponding pair of modules should have the same names,