Clean up application configuration in __init__.py

1 files changed, 53 insertions, 52 deletions

diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index 49ee6902e..f2c6dbb37 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -4,80 +4,81 @@
 Basic Layout
 ============
 
-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.
+The starter files generated by 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``
 ----------------------------------------------
 
-A directory on disk can be turned into a Python :term:`package` by containing
-an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
-package.  We use ``__init__.py`` both as a marker, indicating the directory in
-which it's contained is a package, and to contain application configuration
-code.
+A directory on disk can be turned into a Python :term:`package` by containing an ``__init__.py`` file.
+Even if empty, this marks a directory as a Python package.
+We use ``__init__.py`` both as a marker, indicating the directory in which it is contained is a package, and to contain application configuration code.
 
-When you run the application using the ``pserve`` command using the
-``development.ini`` generated configuration file, the application
-configuration points at a :term:`Setuptools` :term:`entry point` described as
-``egg:tutorial``.  In our application, because the application's ``setup.py``
-file says so, this entry point happens to be the ``main`` function within the
-file named ``__init__.py``.
+When you run the application using the ``pserve`` command using the ``development.ini`` generated configuration file, the application configuration points at a :term:`Setuptools` :term:`entry point` described as ``egg:tutorial``.
+In our application, because the application's ``setup.py`` file says so, this entry point happens to be the ``main`` function within the file named ``__init__.py``.
 
-Open ``tutorial/__init__.py``.  It should already contain the following:
+Open ``tutorial/__init__.py``.
+It should already contain the following:
 
 .. literalinclude:: src/basiclayout/tutorial/__init__.py
-  :linenos:
-  :language: py
+    :linenos:
+    :language: py
+
+#.  *Lines 1-3*.
+    Perform some dependency imports.
+
+#.  *Lines 6-8*.
+    Define a :term:`root factory` for our Pyramid application.
+
+#.  *Line 11*.
+    ``__init__.py`` defines a function named ``main``.
 
-#. *Lines 1-3*.  Perform some dependency imports.
+#.  *Line 14*.
+    Construct a :term:`Configurator` as a :term:`context manager` with the ``settings`` keyword parsed by :term:`PasteDeploy`.  See :term:`Deployment settings`.
 
-#. *Lines 6-8*.  Define a :term:`root factory` for our Pyramid application.
+#.  *Line 15*.
+    Use an explicit transaction manager for apps so that they do not implicitly create new transactions when touching the manager outside of the ``pyramid_tm`` lifecycle.
 
-#. *Line 11*.  ``__init__.py`` defines a function named ``main``.
+#.  *Line 16*.
+    Include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction <https://pypi.org/project/transaction/>`_ package.
 
-#. *Line 14*.  Use an explicit transaction manager for apps so that they do not implicitly create new transactions when touching the manager outside of the ``pyramid_tm`` lifecycle.
+#.  *Line 17*.
+    Include support for ``pyramid_retry`` to retry a request when transient exceptions occur.
 
-#. *Line 15*.  Construct a :term:`Configurator` as a :term:`context manager` with the settings keyword parsed by :term:`PasteDeploy`.
+#.  *Line 18*.
+    Include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application.
 
-#. *Line 16*.  Include support for the :term:`Chameleon` template rendering
-   bindings, allowing us to use the ``.pt`` templates.
+#.  *Line 19*.
+    Set a root factory using our function named ``root_factory``.
 
-#. *Line 17*.  Include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction <https://pypi.org/project/transaction/>`_ package.
+#.  *Line 20*.
+    Include support for the :term:`Chameleon` template rendering bindings, allowing us to use the ``.pt`` templates.
 
-#. *Line 18*.  Include support for ``pyramid_retry`` to retry a request when transient exceptions occur.
+#.  *Line 21*.
+    Include routes from the ``.routes`` module.
+    This registers a "static view" using the :meth:`pyramid.config.Configurator.add_static_view` method.
+    This view answers requests whose URL path starts with ``/static``.
+    This statement registers a view that will serve up static assets, such as CSS and image files.
+    In this case the URL will answer requests at ``http://localhost:6543/static/`` and below.
 
-#. *Line 19*.  Include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application.
+    The first argument is the "name" ``static``, which indicates that the URL path prefix of the view will be ``/static``.
 
-#. *Line 20*.  Set a root factory using our function named ``root_factory``.
+    The second argument of this method is the "path".
+    It is a relative :term:`asset specification`.
+    It finds the resources it should serve within the ``static`` directory inside the ``tutorial`` package.
+    Alternatively the cookiecutter could have used an *absolute* asset specification as the path (``tutorial:static``).
 
-#. *Line 21*.  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
-   and image files, for us, in this case, at
-   ``http://localhost:6543/static/`` and below.  The first argument is the
-   "name" ``static``, which indicates that the URL path prefix of the view
-   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 cookiecutter could have used an *absolute* asset
-   specification as the path (``tutorial:static``).
+    The third argument is an optional ``cache_max_age`` which specifies the number of seconds the static asset will be HTTP-cached.
 
-#. *Line 22*.  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 cookiecutter could have equivalently said ``config.scan('tutorial')``, but
-   it chose to omit the package name argument.
+#.  *Line 22*.
+    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.
+    It 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 cookiecutter could have equivalently said ``config.scan('tutorial')``, but it chose to omit the package name argument.
 
-#. *Line 23*.  Use the
-   :meth:`pyramid.config.Configurator.make_wsgi_app` method
-   to return a :term:`WSGI` application.
+#.  *Line 23*.
+    Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application.
 
 Resources and models with ``models.py``
 ---------------------------------------