From 641a788dc61acf2efb91f4d2a196cb585d89a47b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:14:31 -0600 Subject: Rework sentence to simplify --- docs/narr/startup.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 17926c716..7ce36f05e 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -48,9 +48,9 @@ Here's a high-level time-ordered overview of what happens when you press 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 + ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. + This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + 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 -- cgit v1.2.3 From d728e112303a1eabd774fb2b8fde7d117422222d Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:15:16 -0600 Subject: Split paragraph in two --- docs/narr/startup.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 7ce36f05e..a72b89d4c 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -50,6 +50,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + 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 -- cgit v1.2.3 From 197a77b5783151c742e335235323627c0538b2a6 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:16:08 -0600 Subject: Split long sentence into two and clarify each --- docs/narr/startup.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index a72b89d4c..f740baadf 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,11 +68,9 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for this 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 *constructor* is named by the entry point referenced on the ``use=`` line of the ``ini`` section which configures your :app:`Pyramid` application. + It is passed the key/value parameters mentioned within the this section. + The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. For :app:`Pyramid` applications, the constructor will be a function named ``main`` in the ``__init__.py`` file within the :term:`package` in which -- cgit v1.2.3 From d9137a9b888271cdd9e52d5e885fd04589b67578 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:53:40 -0600 Subject: Simply sentences by adding hyperlinks --- docs/narr/startup.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index f740baadf..6c5fe8f60 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -47,10 +47,14 @@ 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 becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + .. _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 @@ -68,8 +72,8 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for this application. See :ref:`logging_config` for more information. -#. The application's *constructor* is named by the entry point referenced on the ``use=`` line of the ``ini`` section which configures your :app:`Pyramid` application. - It is passed the key/value parameters mentioned within the this section. +#. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. + It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. For :app:`Pyramid` applications, the constructor will be a function named -- cgit v1.2.3 From fbf42997374321d395be9ff11a264954e0fcb70e Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:54:06 -0600 Subject: Use present tense instead of future tense --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 6c5fe8f60..baa31000d 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -76,7 +76,7 @@ Here's a high-level time-ordered overview of what happens when you press It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor is meant to 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 -- cgit v1.2.3 From 799810caee1b9acb74950dbc5b0f003a386f8a38 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:55:16 -0600 Subject: Better english --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index baa31000d..eb255d527 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -74,7 +74,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. It is passed the key/value parameters in :ref:`the application's .ini section `. - The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. + The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. For :app:`Pyramid` applications, the constructor is a function named ``main`` in the ``__init__.py`` file within the :term:`package` in which -- cgit v1.2.3 From 2ce055b7f3e81b363d25925276fe7bbcad705be7 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:59:14 -0600 Subject: Remove extra word --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 2acdb33f4..c0008282a 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -39,7 +39,7 @@ format `. This is the same format used as the Python :ref:`logging module's Configuration file format `. 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``. +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 -- cgit v1.2.3 From 8a919fa0efb4448954c70cd1cba9e72f57008cf9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:03:17 -0600 Subject: Split long sentence --- docs/narr/logging.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index c0008282a..ad63b218f 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -37,9 +37,8 @@ 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 `. This is the same format used as the Python :ref:`logging module's Configuration file format `. -The application-related and logging-related sections in the configuration file -can coexist peacefully, and the logging-related sections in the file are used -when you run ``pserve``. +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``. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, a thin wrapper around the :func:`logging.config.fileConfig` using the specified -- cgit v1.2.3 From 28d5c1c17f683a69345ddfe2a27b5c5aa2668d5a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:15:12 -0600 Subject: Improve sentence --- docs/narr/logging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index ad63b218f..408c8fc7c 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -43,8 +43,8 @@ The logging-related sections in the file configure logging 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. +cookiecutter-generated ``.ini`` files do). +``setup_logging`` reads the logging configuration from the ``ini`` file given on the ``pserve`` command line. 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 -- cgit v1.2.3 From 2b306dcb80b9ec510c74f3baa1de2ca23339cfc3 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:34:44 -0600 Subject: Read better --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index eb255d527..29e5436fe 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -70,7 +70,7 @@ Here's a high-level time-ordered overview of what happens when you press #. 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 entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. It is passed the key/value parameters in :ref:`the application's .ini section `. -- cgit v1.2.3 From bc17531c1eb67f2a5eb31b966f2ede63d767b803 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:59:35 -0600 Subject: Split long complicated sentence into 3 --- docs/narr/logging.rst | 9 ++++----- docs/narr/startup.rst | 2 ++ 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 408c8fc7c..b12434317 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -40,11 +40,10 @@ format `. This is the same format used as the Python 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``. -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 given on the ``pserve`` command line. +On :ref:`startup ` the ``pserve`` command :ref:`configures logging ` using the ``.ini`` file given to it. +If the ``.ini`` file contains a ``[loggers]`` section (all of the cookiecutter-generated ``.ini`` files do) ``pserve`` calls the :func:`pyramid.paster.setup_logging` function. +The :func:`setup_logging` function is a thin wrapper around the :func:`logging.config.fileConfig`. +When ``setup_logging`` is passed the ``ini`` file given on the ``pserve`` command line it reads the 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 29e5436fe..ff94f441e 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,6 +68,8 @@ 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. +.. _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 the application. See :ref:`logging_config` for more information. -- cgit v1.2.3 From 27c82826d669e4b381328643f84ccfff5bcba16e Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 01:13:47 -0600 Subject: Add index entries for logging initialization --- docs/narr/logging.rst | 3 +++ docs/narr/startup.rst | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index b12434317..8ae8469de 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -40,6 +40,9 @@ format `. This is the same format used as the Python 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 + On :ref:`startup ` the ``pserve`` command :ref:`configures logging ` using the ``.ini`` file given to it. If the ``.ini`` file contains a ``[loggers]`` section (all of the cookiecutter-generated ``.ini`` files do) ``pserve`` calls the :func:`pyramid.paster.setup_logging` function. The :func:`setup_logging` function is a thin wrapper around the :func:`logging.config.fileConfig`. diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index ff94f441e..e2a18cd60 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,6 +68,9 @@ 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`` -- cgit v1.2.3 From 6ca75ed314188de40a8676bf1258762bc9522b91 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 08:10:47 -0600 Subject: Use numbered list instead of a paragraph per Steve Piercy --- docs/narr/logging.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 8ae8469de..58bd2d4ec 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -43,10 +43,14 @@ The logging-related sections in the file configure logging when you run ``pserve .. index:: pair: logging; startup -On :ref:`startup ` the ``pserve`` command :ref:`configures logging ` using the ``.ini`` file given to it. -If the ``.ini`` file contains a ``[loggers]`` section (all of the cookiecutter-generated ``.ini`` files do) ``pserve`` calls the :func:`pyramid.paster.setup_logging` function. -The :func:`setup_logging` function is a thin wrapper around the :func:`logging.config.fileConfig`. -When ``setup_logging`` is passed the ``ini`` file given on the ``pserve`` command line it reads the file and configures logging. +If the configuration ``.ini`` file, specified when invoking ``pserve``, contains a ``[loggers]`` section then on :ref:`startup ` 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 -- cgit v1.2.3 From a0d75f29020b8763982a9e77fcdca354cf663913 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 08:51:09 -0600 Subject: Say 2 things in separate sentences --- docs/narr/startup.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index e2a18cd60..555663804 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -51,7 +51,8 @@ Here's a high-level time-ordered overview of what happens when you press #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. - This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + This section configures the :term:`WSGI` webserver which serves your application. + As such it is the ``ini`` section for your application and can supply many of your application's :term:`settings`. .. _entry_point_discovery: -- cgit v1.2.3 From ee8033a6b1292bc9a65151e34cdc34dcffd33efb Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 08:52:34 -0600 Subject: Shorten and fix sentence per Steve Piercy --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 555663804..af9415cc9 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -78,7 +78,7 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for the application. See :ref:`logging_config` for more information. -#. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. +#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned ` ``use=`` line, is the application's *constructor*. It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. -- cgit v1.2.3 From 21bff45c53e06d283518265b5381450b2f188944 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 09:18:53 -0600 Subject: Add "constructor" glossary entry --- docs/glossary.rst | 7 +++++++ docs/narr/startup.rst | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) 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 ` 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/startup.rst b/docs/narr/startup.rst index af9415cc9..0b3680bca 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -78,7 +78,7 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for the application. See :ref:`logging_config` for more information. -#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned ` ``use=`` line, is the application's *constructor*. +#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned ` ``use=`` line, is the application's :term:`constructor`. It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. -- cgit v1.2.3 From a86f9f56067c80eedbdabc4c983628e2aa31479d Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 09:41:51 -0600 Subject: Better wording --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 0b3680bca..65669e0b9 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -52,7 +52,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[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 supply many of your application's :term:`settings`. + 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: -- cgit v1.2.3