Merge pull request #3429 from kpinc/logging

Clarify startup and logging related docs

3 files changed, 40 insertions, 19 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 7f396dc7d..89c03860b 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1219,3 +1219,10 @@ Glossary
       Settings are collected at application startup.
       They can affect all the components which make up the the application.
       Pyramid itself, any tweens or Pyramid add-ons used, and :ref:`your own code may reference <deployment_settings>` and act on settings.
+
+   constructor
+      A function returning a Pyramid :term:`WSGI` application.
+      Every Pyramid application has a single constructor function named ``main``.
+      It returns a Pyramid :term:`router` generated by a :term:`configurator`, and is written by you.
+      The Pyramid constructor is the application's :term:`entry point`.
+
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index 2acdb33f4..58bd2d4ec 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -37,15 +37,20 @@ These ``.ini`` file sections are passed to the `logging module's config file con
 PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser
 format <ConfigParser>`. This is the same format used as the Python
 :ref:`logging module's Configuration file format <logging-config-fileformat>`.
-The application-related and logging-related sections in the configuration file
-can coexist peacefully, and the logging-related sections in the file are used
-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
-cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging
-configuration from the ini file upon which ``pserve`` was invoked.
+The application-related and logging-related sections in the configuration file can coexist peacefully.
+The logging-related sections in the file configure logging when you run ``pserve``.
+
+.. index::
+   pair: logging; startup
+
+If the configuration ``.ini`` file, specified when invoking ``pserve``, contains a ``[loggers]`` section then on :ref:`startup <the_startup_process>` the following process takes place:
+
+#.  The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, passing the ``.ini`` file.
+
+#.  ``setup_logging`` is a thin wrapper which calls the Python standard library's :func:`logging.config.fileConfig`.
+
+#.  :func:`logging.config.fileConfig` reads the logging configuration from the ``.ini`` file and configures logging.
+
 
 Default logging configuration is provided in both the default
 ``development.ini`` and the ``production.ini`` files.  If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 17926c716..65669e0b9 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -47,10 +47,16 @@ Here's a high-level time-ordered overview of what happens when you press
    the :term:`PasteDeploy` library and returns a parser that can understand
    the format.
 
+.. _ini_section_discovery:
+
 #. The :term:`PasteDeploy` finds a section named either ``[app:main]``,
-   ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file.  This
-   section represents the configuration of a :term:`WSGI` application that will
-   be served.  If you're using a simple application (e.g., ``[app:main]``), the
+   ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file.
+   This section configures the :term:`WSGI` webserver which serves your application.
+   As such it is the ``ini`` section for your application and can be the source for many of your application's :term:`settings`.
+
+   .. _entry_point_discovery:
+
+   If you're using a simple application (e.g., ``[app:main]``), the
    application's ``paste.app_factory`` :term:`entry point` will be named on the
    ``use=`` line within the section's configuration.  If instead of a simple
    application, you're using a WSGI :term:`pipeline` (e.g., a
@@ -63,17 +69,20 @@ Here's a high-level time-ordered overview of what happens when you press
    will have a single ``[app:main]`` section in it, and this will be the
    application served.
 
+.. index::
+   pair: logging; startup
+
+.. _startup_logging_initialization:
+
 #. The framework finds all :mod:`logging` related configuration in the ``.ini``
    file and uses it to configure the Python standard library logging system for
-   this application.  See :ref:`logging_config` for more information.
+   the application.  See :ref:`logging_config` for more information.
 
-#. The application's *constructor* named by the entry point referenced on the
-   ``use=`` line of the section representing your :app:`Pyramid` application is
-   passed the key/value parameters mentioned within the section in which it's
-   defined.  The constructor is meant to return a :term:`router` instance,
-   which is a :term:`WSGI` application.
+#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned <entry_point_discovery>` ``use=`` line, is the application's :term:`constructor`.
+   It is passed the key/value parameters in :ref:`the application's .ini section <ini_section_discovery>`.
+   The constructor should return a :term:`router` instance, which is a :term:`WSGI` application.
 
-   For :app:`Pyramid` applications, the constructor will be a function named
+   For :app:`Pyramid` applications, the constructor is a function named
    ``main`` in the ``__init__.py`` file within the :term:`package` in which
    your application lives.  If this function succeeds, it will return a
    :app:`Pyramid` :term:`router` instance.  Here's the contents of an example