From 87c8da5865c001ff0ca9ef2c923e26e323ccfcde Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 29 Oct 2018 13:39:31 -0500 Subject: Describe the points at which ini files are processed --- docs/narr/project.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 725263407..218545193 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -611,6 +611,8 @@ The generated ``development.ini`` file looks like so: This file contains several sections including ``[app:main]``, ``[server:main]``, and several other sections related to logging configuration. +.. _app_main: + The ``[app:main]`` section represents configuration for your :app:`Pyramid` application. The ``use`` setting is the only setting required to be present in the ``[app:main]`` section. Its default value, ``egg:myproject``, indicates @@ -834,6 +836,11 @@ Pyramid developers can get up to speed quickly on your code when you need help. .. index:: single: __init__.py + single: ini file processing + pair: conflict resolution; ini file + pair: add-on; configuration + pair: logging; configuration + pair: PasteDeploy; configuration .. _init_py: @@ -856,12 +863,16 @@ also informs Python that the directory which contains it is a *package*. WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. - Within this function, application configuration is performed. + Before ``main`` is called :term:`PasteDeploy` :ref:`configures logging `. + Within ``main`` further application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. + This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. + Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings, allowing us to - specify renderers with the ``.jinja2`` extension. + Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. + The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. + Consult your add-on's documentation. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 9ef620f65721aa8474e8bde2e6b13673ed980f73 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 30 Oct 2018 12:56:44 -0500 Subject: mmerickel noted that add-ons may not get their settings from .ini files Also, remove detail about Configurator returning a configuration. --- docs/narr/project.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 218545193..11302fcf9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -867,12 +867,12 @@ also informs Python that the directory which contains it is a *package*. Within ``main`` further application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. - This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. + This applies lines in the ``.ini`` file. Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. - The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. - Consult your add-on's documentation. + Line 8 adds support for Jinja2 templating bindings. + Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. + These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From d5efd3c665952e67953405b794d0e2bb02689a86 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 30 Oct 2018 13:05:51 -0500 Subject: Remove unnecessary words --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 11302fcf9..9fde7918f 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -872,7 +872,7 @@ also informs Python that the directory which contains it is a *package*. Line 8 adds support for Jinja2 templating bindings. Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. - These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. + The source of these settings are add-on dependent. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 7741aaa13bb266f5822b742bb5fda5cbc41d77c9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 18:52:27 -0600 Subject: Revert "Remove unnecessary words" This reverts commit d5efd3c665952e67953405b794d0e2bb02689a86. --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9fde7918f..11302fcf9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -872,7 +872,7 @@ also informs Python that the directory which contains it is a *package*. Line 8 adds support for Jinja2 templating bindings. Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. - The source of these settings are add-on dependent. + These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 6cb6e15090e527250d41df81dc4a56c56114b3a3 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 18:52:39 -0600 Subject: Revert "mmerickel noted that add-ons may not get their settings from .ini files" This reverts commit 9ef620f65721aa8474e8bde2e6b13673ed980f73. --- docs/narr/project.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 11302fcf9..218545193 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -867,12 +867,12 @@ also informs Python that the directory which contains it is a *package*. Within ``main`` further application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. - This applies lines in the ``.ini`` file. + This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings. - Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. - These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. + Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. + The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. + Consult your add-on's documentation. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From d9e378525bdce3feab8d842fe73afc1a5462f8d4 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 18:52:43 -0600 Subject: Revert "Describe the points at which ini files are processed" This reverts commit 87c8da5865c001ff0ca9ef2c923e26e323ccfcde. --- docs/narr/project.rst | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 218545193..725263407 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -611,8 +611,6 @@ The generated ``development.ini`` file looks like so: This file contains several sections including ``[app:main]``, ``[server:main]``, and several other sections related to logging configuration. -.. _app_main: - The ``[app:main]`` section represents configuration for your :app:`Pyramid` application. The ``use`` setting is the only setting required to be present in the ``[app:main]`` section. Its default value, ``egg:myproject``, indicates @@ -836,11 +834,6 @@ Pyramid developers can get up to speed quickly on your code when you need help. .. index:: single: __init__.py - single: ini file processing - pair: conflict resolution; ini file - pair: add-on; configuration - pair: logging; configuration - pair: PasteDeploy; configuration .. _init_py: @@ -863,16 +856,12 @@ also informs Python that the directory which contains it is a *package*. WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. - Before ``main`` is called :term:`PasteDeploy` :ref:`configures logging `. - Within ``main`` further application configuration is performed. + Within this function, application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. - This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. - Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. - The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. - Consult your add-on's documentation. + Line 8 adds support for Jinja2 templating bindings, allowing us to + specify renderers with the ``.jinja2`` extension. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 9d194007b15c67698adf66c0b94aba1f617a7a6a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 20:56:56 -0600 Subject: Simplify sentence --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 725263407..89cebd063 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -856,7 +856,7 @@ also informs Python that the directory which contains it is a *package*. WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. - Within this function, application configuration is performed. + The ``main`` function configures the application. Line 7 opens a context manager with an instance of a :term:`Configurator`. -- cgit v1.2.3 From 807d5c77801e3d038aa21151235e91496b70fb84 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 21:13:11 -0600 Subject: Link to startup docs for more detail --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 89cebd063..3522ea964 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -871,6 +871,8 @@ also informs Python that the directory which contains it is a *package*. Line 11 returns a :term:`WSGI` application to the caller of the function (Pyramid's pserve). + See :ref:`the_startup_process` for more about the application's :ref:`settings ` and ``main``\'s :ref:`arguments ` and statements. + .. index:: single: routes.py -- cgit v1.2.3 From 1ec0ca5c5325953adb4e96313f7ff8bbedb87e13 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:36:44 -0600 Subject: Move sentence from project docs to logging docs --- docs/narr/project.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 3522ea964..d84b740e3 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -658,10 +658,8 @@ only (``127.0.0.1``). .. _myproject_ini_logging: The sections after ``# logging configuration`` represent Python's standard -library :mod:`logging` module configuration for your application. These -sections are passed to the `logging module's config file configuration engine -`_ when the -``pserve`` or ``pshell`` commands are executed. The default configuration +library :mod:`logging` module configuration for your application. +The default configuration sends application logging output to the standard error output of your terminal. For more information about logging configuration, see :ref:`logging_chapter`. -- cgit v1.2.3 From 6faa22ebcd16fd69d82b756907693f43b0cc29f1 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:42:34 -0600 Subject: Shorten sentence --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index d84b740e3..81fe4032c 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -661,7 +661,7 @@ The sections after ``# logging configuration`` represent Python's standard library :mod:`logging` module configuration for your application. The default configuration sends application logging output to the standard error output of your terminal. -For more information about logging configuration, see :ref:`logging_chapter`. +For more information see :ref:`logging_chapter`. See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other -- cgit v1.2.3 From 481ff76158333826f1de599c3b76e81981a2e8f0 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 00:41:20 -0600 Subject: Make index entries for statup distinct --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 81fe4032c..a5433b278 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -297,7 +297,7 @@ path to the module on which we want to run tests and coverage. single: running an application single: pserve single: reload - single: startup + single: starting .. _running_the_project_application: -- cgit v1.2.3 From fecab4645f4f546aaa5e9aa69ea31fea1ffa2446 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 08:22:12 -0600 Subject: Put reference to startup in a seealso --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index a5433b278..69e80fcfb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -869,6 +869,8 @@ also informs Python that the directory which contains it is a *package*. Line 11 returns a :term:`WSGI` application to the caller of the function (Pyramid's pserve). +.. seealso:: + See :ref:`the_startup_process` for more about the application's :ref:`settings ` and ``main``\'s :ref:`arguments ` and statements. -- cgit v1.2.3 From 5fc9ed4bed9d0a80009a5cf5d3d191d535b8150f Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 11:59:37 -0600 Subject: Link to "settings" glossary entry when settings are first introduced --- docs/narr/project.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 69e80fcfb..14f0d083e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -139,8 +139,8 @@ or install your application for deployment or development. An ``.ini`` file named ``development.ini`` will be created in the project directory. You will use this ``.ini`` file to configure a server, to run your -application, and to debug your application. It contains configuration that -enables an interactive debugger and settings optimized for development. +application, and to debug your application. +It contains configuration that enables an interactive debugger and :term:`settings` optimized for development. Another ``.ini`` file named ``production.ini`` will also be created in the project directory. It contains configuration that disables any interactive -- cgit v1.2.3