add some simple notes about plaster in the narrative docs

Michael Merickel

2017-03-31 f454b80b0f6e6442fa27e48b7e1e38c5a7cbef03

add some simple notes about plaster in the narrative docs

 CHANGES.txt

@@ -7,7 +7,7 @@
- The file format used by all ``p*`` command line scripts such as ``pserve``
  and ``pshell``, as well as the ``pyramid.paster.bootstrap`` function
  is now replaceable thanks to a new dependency on
  `plaster <http://docs.pylonsproject.org/projects/plaster/en/latest/>`.
  `plaster <http://docs.pylonsproject.org/projects/plaster/en/latest/>`_.

  For now, Pyramid is still shipping with integrated support for the
  PasteDeploy INI format by depending on the ``plaster_pastedeploy`` binding.
@@ -16,12 +16,12 @@

- Added an execution policy hook to the request pipeline. An execution
  policy has the ability to control creation and execution of the request
  objects before they enter rest of the pipeline. This means for a single
  objects before they enter the rest of the pipeline. This means for a single
  request environ the policy may create more than one request object.

  The first library to use this feature is
  `pyramid_retry
  <http://docs.pylonsproject.org/projects/pyramid-retry/en/latest/>`.
  <http://docs.pylonsproject.org/projects/pyramid-retry/en/latest/>`_.

  See https://github.com/Pylons/pyramid/pull/2964


 docs/glossary.rst

@@ -366,6 +366,14 @@
     :term:`WSGI` components together declaratively within an ``.ini``
     file.  It was developed by Ian Bicking.

   plaster
     `plaster <http://docs.pylonsproject.org/projects/plaster/en/latest/>`_ is
     a library used by :app:`Pyramid` which acts as an abstraction between
     command-line scripts and the file format used to load the :term:`WSGI`
     components and application settings. By default :app:`Pyramid` ships
     with the ``plaster_pastedeploy`` library installed which provides
     integrated support for loading a :term:`PasteDeploy` INI file.

   Chameleon
     `chameleon <https://chameleon.readthedocs.org/en/latest/>`_ is an
     attribute language template compiler which supports the :term:`ZPT`

 docs/narr/paste.rst

@@ -26,12 +26,7 @@
PasteDeploy
-----------

:term:`PasteDeploy` is the system that Pyramid uses to allow :term:`deployment
settings` to be specified using an ``.ini`` configuration file format.  It also
allows the ``pserve`` command to work.  Its configuration format provides a
convenient place to define application :term:`deployment settings` and WSGI
server settings, and its server runner allows you to stop and start a Pyramid
application easily.
:term:`plaster` is the system that Pyramid uses to load settings from configuration files. The most common format for these files is an ``.ini`` format structured in a way defined by :term:`PasteDeploy`.  The format supports mechanisms to define WSGI app :term:`deployment settings`, WSGI server settings and logging. This allows the ``pserve`` command to work, allowing you to stop and start a Pyramid application easily.

.. _pastedeploy_entry_points:

@@ -96,3 +91,8 @@
file.  The values in a ``[DEFAULT]`` section will be passed to your
application's ``main`` function as ``global_config`` (see the reference to the
``main`` function in :ref:`init_py`).

Alternative Configuration File Formats
--------------------------------------

It is possible to use different file formats with :app:`Pyramid` if you do not like :term:`PasteDeploy`. Under the hood all command-line scripts such as ``pserve`` and ``pshell`` pass the ``config_uri`` (e.g. ``development.ini`` or ``production.ini``) to the :term:`plaster` library which performs a lookup for an appropriate parser. For ``.ini`` files it uses PasteDeploy but you can register your own configuration formats that plaster will find instead.

 docs/narr/startup.rst

@@ -38,7 +38,14 @@
   begin to run and serve an application using the information contained
   within the ``development.ini`` file.

#. The framework finds a section named either ``[app:main]``,
#. ``pserve`` passes the ``development.ini`` path to :term:`plaster` which
   finds an available configuration loader that recognizes the ``ini`` format.

#. :term:`plaster` finds the ``plaster_pastedeploy`` library which binds
   the :term:`PasteDeploy` library and returns a parser that can understand
   the format.

#. 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