From ae5f2b9da9583114f3f5a6f08497e5a248e3e960 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 27 Sep 2013 20:47:28 -0500 Subject: Docs: Make clear that installation is into the virtual enviornment. --- 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 f3050f805..602f15fef 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -193,10 +193,10 @@ Elided output from a run of this command on UNIX is shown below: ... Finished processing dependencies for MyProject==0.0 -This will install a :term:`distribution` representing your project into the -interpreter's library set so it can be found by ``import`` statements and by -other console scripts such as ``pserve``, ``pshell``, ``proutes`` and -``pviews``. +This will install a :term:`distribution` representing your project +into the virtual environment interpreter's library set so it can be +found by ``import`` statements and by other console scripts such as +``pserve``, ``pshell``, ``proutes`` and ``pviews``. .. index:: single: running tests -- cgit v1.2.3 From bc3de3f5499e39e67e29b6678503f3a14be0b08c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 1 Oct 2013 00:14:12 -0500 Subject: Docs: project.rst: Match parenthesis & fix punctuation. --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 602f15fef..fc3cac009 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -974,9 +974,9 @@ named ``views`` instead of within a single ``views.py`` file, you might: - *Move* the existing ``views.py`` file to a file inside the new ``views`` directory named, say, ``blog.py``. -- Create a file within the new ``views`` directory named ``__init__.py`` (it - can be empty, this just tells Python that the ``views`` directory is a - *package*. +- Create a file within the new ``views`` directory named ``__init__.py``. (It + can be empty. This just tells Python that the ``views`` directory is a + *package*.) You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable -- cgit v1.2.3 From 128d9d6cd92ddd50dfcdf14b12cc94a0902c0df1 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 1 Oct 2013 00:22:20 -0500 Subject: Docs: project.rst: Note that asset specs must be fully qualifed when moving views into a sub-package. --- docs/narr/project.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fc3cac009..1b98271fb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -971,13 +971,16 @@ named ``views`` instead of within a single ``views.py`` file, you might: - Create a ``views`` directory inside your ``myproject`` package directory (the same directory which holds ``views.py``). -- *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. - - Create a file within the new ``views`` directory named ``__init__.py``. (It can be empty. This just tells Python that the ``views`` directory is a *package*.) +- *Move* the existing ``views.py`` file to a file inside the new ``views`` + directory named, say, ``blog.py``. The template :term:`asset + specification`s in ``blog.py`` must now be fully qualified with the + project's package name (``myproject:templates/blog.pt``) since the + ``templates`` directory remains in the ``myproject`` package. + You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable functions to the ``views`` directory. As long as you use the -- cgit v1.2.3 From ac7d1752e071fb7dadbfbf7f4bd1efadd3052b4f Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 1 Oct 2013 00:44:16 -0500 Subject: Docs: project.rst: Make the sentence more better. --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 1b98271fb..e5da3b5c5 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -976,10 +976,10 @@ named ``views`` instead of within a single ``views.py`` file, you might: *package*.) - *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. The template :term:`asset + directory named, say, ``blog.py``. Because the ``templates`` directory + remains in the ``myproject`` package the template :term:`asset specification`s in ``blog.py`` must now be fully qualified with the - project's package name (``myproject:templates/blog.pt``) since the - ``templates`` directory remains in the ``myproject`` package. + project's package name (``myproject:templates/blog.pt``). You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable -- cgit v1.2.3 From 1a76ed41b133ea73c7d40997c6f564fd72d7273e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 1 Oct 2013 00:48:53 -0700 Subject: Add comma --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index e5da3b5c5..4c19982d6 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -144,7 +144,7 @@ contains no space characters, so it's wise to *avoid* a path that contains i.e. ``My Documents``. As a result, the author, when he uses Windows, just puts his projects in ``C:\projects``. -.. warning:: +.. warning:: You’ll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you @@ -977,7 +977,7 @@ named ``views`` instead of within a single ``views.py`` file, you might: - *Move* the existing ``views.py`` file to a file inside the new ``views`` directory named, say, ``blog.py``. Because the ``templates`` directory - remains in the ``myproject`` package the template :term:`asset + remains in the ``myproject`` package, the template :term:`asset specification`s in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). @@ -1028,7 +1028,7 @@ server. Waitress is a server that is suited for development and light production usage. It's not the fastest nor the most featureful WSGI server. Instead, its main feature is that it works on all platforms that Pyramid needs to run on, making it a good choice as a default server from the -perspective of Pyramid's developers. +perspective of Pyramid's developers. Any WSGI server is capable of running a :app:`Pyramid` application. But we suggest you stick with the default server for development, and that you wait -- cgit v1.2.3 From f24ac4c471a458aec0cde232925c8fab652bafcc Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 11:31:47 -0500 Subject: Docs: project.rst: Eliminate reduncency and better explain renderer. --- docs/narr/project.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 602f15fef..09e07ee6d 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -871,18 +871,17 @@ specification` that specifies the ``mytemplate.pt`` file within the ``templates`` directory of the ``myproject`` package. The asset specification could have also been specified as ``myproject:templates/mytemplate.pt``; the leading package name and colon is -optional. The template file it actually points to is a :term:`Chameleon` ZPT -template file. +optional. The template file pointed to is a :term:`Chameleon` ZPT +template file (``templates/my_template.pt``). This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -This view returns a dictionary. When this view is invoked, a -:term:`renderer` converts the dictionary returned by the view into HTML, and -returns the result as the :term:`response`. This view is configured to -invoke a renderer which uses a :term:`Chameleon` ZPT template -(``templates/my_template.pt``). +This view is configured to invoke a :term;`renderer` on a template. The +dictionary the view returns (on line 6) provides the value the renderer +substitutes into the template when generating HTML. The renderer then +returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -- cgit v1.2.3 From 77edee7e91356f4f0f1d12c2dd159965b0576109 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 11:33:50 -0500 Subject: Docs: project.rst: Emphasize key takeaway; use dicts to supply values to templates. --- 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 09e07ee6d..359fb31d3 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,6 +878,8 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. +.. note:: Dictionaries (typically) provide values to :term:`template`s. + This view is configured to invoke a :term;`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From 5bf27497638ad607f0e42feb10145cd6720b74d3 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 15:20:59 -0500 Subject: Docs: Make statements more concreate regards renderers getting data from dictionaries. --- 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 9a1ba190d..61b6ae316 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,7 +878,7 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries (typically) provide values to :term:`template`s. +.. note:: Dictionaries provide values to :term:`template`s. This view is configured to invoke a :term;`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer -- cgit v1.2.3 From 47e13e042c270f9ffb3ac86b294e89ec4b1fef6a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 2 Oct 2013 15:27:32 -0500 Subject: Docs: project.rst: Fix markup failure just introduced. --- 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 61b6ae316..2acc81e17 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -880,7 +880,7 @@ This view callable function is handed a single piece of information: the .. note:: Dictionaries provide values to :term:`template`s. -This view is configured to invoke a :term;`renderer` on a template. The +This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then returns the HTML in a :term:`response`. -- cgit v1.2.3 From 4122733091d0204b22d7acedfdf985caed17f93f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 17:29:39 -0400 Subject: get rid of note that appears to be explained in the next para --- docs/narr/project.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 2acc81e17..bfd00d3a0 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,8 +878,6 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries provide values to :term:`template`s. - This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From ab2fedf7adaec0a56a69beed35312c88d7961c6c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 17:47:17 -0400 Subject: fix the docs build and get rid of stray references to Beaker --- 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 bfd00d3a0..9451f41b1 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -977,7 +977,7 @@ named ``views`` instead of within a single ``views.py`` file, you might: - *Move* the existing ``views.py`` file to a file inside the new ``views`` directory named, say, ``blog.py``. Because the ``templates`` directory remains in the ``myproject`` package, the template :term:`asset - specification`s in ``blog.py`` must now be fully qualified with the + specification` values in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). You can then continue to add view callable functions to the ``blog.py`` -- cgit v1.2.3 From cabaa67149f95796aac35a19313ca543064a7a0b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 5 Oct 2013 00:56:39 -0500 Subject: Docs: project.rst: Hilight that dictionaries provide values to templates. --- 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 9451f41b1..8788977c7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -878,6 +878,8 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. +.. note:: Dictionaries provide values to :term:`template`\s. + This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then -- cgit v1.2.3 From 0f5e17a983ecb97bb0bdeb169ac775886c9e15fe Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 09:53:06 -0500 Subject: Docs: project.rst: Utilize sidebars for out-of-band text. --- docs/narr/project.rst | 58 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 24 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8788977c7..622f40d69 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -210,6 +210,12 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). +.. sidebar:: Verbose Testing + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + On UNIX: .. code-block:: text @@ -243,12 +249,6 @@ Here's sample output from a test run on UNIX: OK -.. note:: - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. @@ -684,6 +684,14 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. +.. sidebar:: Python's ``setup.py`` + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + .. index:: single: setup.py @@ -694,14 +702,6 @@ The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing, packaging, and distributing your application. -.. note:: - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,6 +857,26 @@ and which returns a :term:`response`. :language: python :linenos: +.. sidebar:: Fully Interactive Development + + Because our ``development.ini`` has a ``pyramid.reload_templates = + true`` directive indicating that templates should be reloaded when + they change, you won't need to restart the application server to + see changes you make to templates. During development, this is + handy. If this directive had been ``false`` (or if the directive + did not exist), you would need to restart the application server + for each template change. For production applications, you should + set your project's ``pyramid.reload_templates`` to ``false`` to + increase template rendering speed. + + Pyramid can also dynamically reload changed Python files. For more + on this see :ref:`reloading_code` above. + + The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows + interactive access to traceback execution stack frames from the + Python interpreter. + Lines 4-6 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). @@ -888,16 +908,6 @@ returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. - .. index:: single: static directory -- cgit v1.2.3 From 5276ce567b1c04e3d4cadcfb7f41b135296b1d39 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 09:55:07 -0500 Subject: Docs: project.rst: Move note that tempates get values from dictionaries down a paragraph. --- 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 622f40d69..fc1d473ac 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -898,13 +898,13 @@ This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -.. note:: Dictionaries provide values to :term:`template`\s. - This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer substitutes into the template when generating HTML. The renderer then returns the HTML in a :term:`response`. +.. note:: Dictionaries provide values to :term:`template`\s. + See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -- cgit v1.2.3 From 56170f30f6cd1d4268d9e5b0cd24a75c645ab0ca Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 7 Oct 2013 21:00:26 -0500 Subject: Docs: project.rst: Reword template reload note per Steve Piercy's suggestions. Take care to retain the thought that the defaults setup by the scaffold cause automatic template reload. This patch should be applied before the docs_dict_note branch. --- docs/narr/project.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9451f41b1..0de46c806 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -886,15 +886,16 @@ returns the HTML in a :term:`response`. See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. +.. note:: ``development.ini`` has a setting that controls how templates are + reloaded: ``pyramid.reload_templates``. + + - A setting of ``True`` (as in the scaffold ``development.ini``) + automatically reloads changed templates without a server restart. This + is convenient while developing but slows template rendering speed. + + - A setting of ``False`` (the default) requires a server restart to + integrate template changes. Production applications should set + ``pyramid.reload_templates = False``. .. index:: single: static directory -- cgit v1.2.3 From 5ded35a5d057eb6188d6f80c47593ec934833d47 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:32:14 -0700 Subject: - straighten out difference between content and its presentation, re: admonitions of note, seealse, sidebar --- docs/narr/project.rst | 79 +++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 46 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4397c09b..fcce9fac4 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -146,7 +146,7 @@ puts his projects in ``C:\projects``. .. warning:: - You’ll need to avoid using ``pcreate`` to create a project with the same + You'll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you should avoid using the names ``site`` or ``test``, both of which conflict with Python standard library packages. You should also avoid @@ -210,12 +210,6 @@ Python interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). -.. sidebar:: Verbose Testing - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - On UNIX: .. code-block:: text @@ -253,6 +247,12 @@ The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. +.. note:: + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + .. index:: single: running an application single: pserve @@ -684,14 +684,6 @@ use a different version control system, you may need to install a setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. -.. sidebar:: Python's ``setup.py`` - - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. - .. index:: single: setup.py @@ -702,6 +694,14 @@ The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing, packaging, and distributing your application. +.. note:: + + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The + Hitchhiker's Guide to Packaging `_. + Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py @@ -857,26 +857,6 @@ and which returns a :term:`response`. :language: python :linenos: -.. sidebar:: Fully Interactive Development - - Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to - increase template rendering speed. - - Pyramid can also dynamically reload changed Python files. For more - on this see :ref:`reloading_code` above. - - The :ref:`debug_toolbar` provides interactive access to your - application's internals and, should an exception occur, allows - interactive access to traceback execution stack frames from the - Python interpreter. - Lines 4-6 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). @@ -905,20 +885,27 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. -See :ref:`views_which_use_a_renderer` for more information about how views, -renderers, and templates relate and cooperate. - .. note:: ``development.ini`` has a setting that controls how templates are - reloaded: ``pyramid.reload_templates``. - - - A setting of ``True`` (as in the scaffold ``development.ini``) - automatically reloads changed templates without a server restart. This - is convenient while developing but slows template rendering speed. - - - A setting of ``False`` (the default) requires a server restart to - integrate template changes. Production applications should set + reloaded, ``pyramid.reload_templates``. + + - When set to ``True`` (as in the scaffold ``development.ini``) changed + templates automatically reload without a server restart. This is + convenient while developing, but slows template rendering speed. + + - When set to ``False`` (the default value), changing templates requires + a server restart to reload them. Production applications should use ``pyramid.reload_templates = False``. +.. seealso:: See also :ref:`views_which_use_a_renderer` for more information + about how views, renderers, and templates relate and cooperate. + +.. seealso:: Pyramid can also dynamically reload changed Python files. For + more on this see :ref:`reloading_code`. + +.. seealso:: The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows interactive + access to traceback execution stack frames from the Python interpreter. + .. index:: single: static directory -- cgit v1.2.3 From 716bdf37573ee8ef295ac1d01a1e8ff96c4c0f43 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2013 21:55:30 -0700 Subject: - use clearer subject --- docs/narr/project.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fcce9fac4..8b7c24725 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -984,9 +984,9 @@ named ``views`` instead of within a single ``views.py`` file, you might: can be empty. This just tells Python that the ``views`` directory is a *package*.) -- *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. Because the ``templates`` directory - remains in the ``myproject`` package, the template :term:`asset +- *Move* the content from the existing ``views.py`` file to a file inside the + new ``views`` directory named, say, ``blog.py``. Because the ``templates`` + directory remains in the ``myproject`` package, the template :term:`asset specification` values in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). -- cgit v1.2.3 From eb3b27df0a35088f631680d7f467680662f17bac Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 8 Oct 2013 06:17:13 -0500 Subject: Docs: project.rst: Printf()s can be used for debugging. Output goes to the server console. The main point of the second sentence is to setup the reader with mental context for the 3rd sentence, so that the 3rd sentence sinks in. Likewise, the parenthetical in the second sentence about server startup messages gives the reader some clue as to what the rest of the sentence it talking about. I suspect that some readers won't know what a console is, and the rest will be confused by a server run on a console. --- docs/narr/project.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8b7c24725..a454573f0 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -259,6 +259,8 @@ single sample test exists. single: reload single: startup +.. _running_the_project_application: + Running The Project Application ------------------------------- @@ -600,6 +602,8 @@ server which listens on TCP port 6543. It is configured to listen on all interfaces (``0.0.0.0``). This means that any remote system which has TCP access to your system can see your Pyramid application. +.. _MyProject_ini_logging: + The sections that live between the markers ``# Begin logging configuration`` and ``# End logging configuration`` represent Python's standard library :mod:`logging` module configuration for your application. The sections @@ -885,6 +889,14 @@ returns the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. +.. note:: When the application is run with the scaffold's :ref:`default + development.ini ` configuration :ref:`logging is setup + ` to aid debugging. Should an exception be raised, + uncaught tracebacks are displayed, after the startup messages, on :ref:`the + console running the server `. + Conveniently, ``printf()``\s inserted into the application for debugging + also send output to this console. + .. note:: ``development.ini`` has a setting that controls how templates are reloaded, ``pyramid.reload_templates``. -- cgit v1.2.3 From fd99b0e53835dd7463986c4d705e8de06be7dbe6 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 8 Oct 2013 09:16:10 -0500 Subject: Docs: project.rst: Oops, print(), not printf(). --- 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 a454573f0..9a15649d7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -894,7 +894,7 @@ returns the HTML in a :term:`response`. ` to aid debugging. Should an exception be raised, uncaught tracebacks are displayed, after the startup messages, on :ref:`the console running the server `. - Conveniently, ``printf()``\s inserted into the application for debugging + Conveniently, ``print()``\s inserted into the application for debugging also send output to this console. .. note:: ``development.ini`` has a setting that controls how templates are -- cgit v1.2.3