- add p* scripts - add links to p* scripts - add a blank line to keep indic...

Steve Piercy

2015-12-21 cac59f060511f10bc752e143c61ee1f9defe5064

- add p* scripts
- add links to p* scripts
- add a blank line to keep indices and labels better visually related to the subsequent heading
(cherry picked from commit 5ff3d2d)
(cherry picked from commit 091fd44)

 docs/index.rst

@@ -162,6 +162,19 @@
   api/*


``p*`` Scripts Documentation
============================

``p*`` scripts included with :app:`Pyramid`:.

.. toctree::
   :maxdepth: 1
   :glob:

   pscripts/index
   pscripts/*


Change History
==============


 docs/narr/commandline.rst

@@ -6,6 +6,7 @@
Your :app:`Pyramid` application can be controlled and inspected using a variety
of command-line utilities.  These utilities are documented in this chapter.


.. index::
   pair: matching views; printing
   single: pviews
@@ -14,6 +15,8 @@

Displaying Matching Views for a Given URL
-----------------------------------------

.. seealso:: See also the output of :ref:`pviews --help <pviews_script>`.

For a big application with several views, it can be hard to keep the view
configuration details in your head, even if you defined all the views yourself.
@@ -114,6 +117,8 @@
The Interactive Shell
---------------------

.. seealso:: See also the output of :ref:`pshell --help <pshell_script>`.

Once you've installed your program for development using ``setup.py develop``,
you can use an interactive Python shell to execute expressions in a Python
environment exactly like the one that will be used when your application runs
@@ -178,6 +183,7 @@
    $ $VENV/bin/pshell starter/development.ini

Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).


.. index::
   pair: pshell; extending
@@ -281,6 +287,7 @@

   $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject


.. index::
   pair: routes; printing
   single: proutes
@@ -289,6 +296,8 @@

Displaying All Application Routes
---------------------------------

.. seealso:: See also the output of :ref:`proutes --help <proutes_script>`.

You can use the ``proutes`` command in a terminal window to print a summary of
routes related to your application.  Much like the ``pshell`` command (see
@@ -371,6 +380,8 @@
Displaying "Tweens"
-------------------

.. seealso:: See also the output of :ref:`ptweens --help <ptweens_script>`.

A :term:`tween` is a bit of code that sits between the main Pyramid application
request handler and the WSGI application which calls it.  A user can get a
representation of both the implicit tween ordering (the ordering specified by
@@ -447,6 +458,7 @@

See :ref:`registering_tweens` for more information about tweens.


.. index::
   single: invoking a request
   single: prequest
@@ -455,6 +467,8 @@

Invoking a Request
------------------

.. seealso:: See also the output of :ref:`prequest --help <prequest_script>`.

You can use the ``prequest`` command-line utility to send a request to your
application and see the response body without starting a server.
@@ -505,6 +519,7 @@

   $ $VENV/bin/prequest -mPOST development.ini / < somefile


Using Custom Arguments to Python when Running ``p*`` Scripts
------------------------------------------------------------

@@ -516,10 +531,21 @@

      python -3 -m pyramid.scripts.pserve development.ini


.. index::
   single: pdistreport
   single: distributions, showing installed
   single: showing installed distributions

.. _showing_distributions:

Showing All Installed Distributions and Their Versions
------------------------------------------------------

.. versionadded:: 1.5

.. seealso:: See also the output of :ref:`pdistreport --help
   <pdistreport_script>`.

You can use the ``pdistreport`` command to show the :app:`Pyramid` version in
use, the Python version in use, and all installed versions of Python
@@ -539,6 +565,7 @@
pastebin when you are having problems and need someone with more familiarity
with Python packaging and distribution than you have to look at your
environment.


.. _writing_a_script:

@@ -652,6 +679,7 @@
object present in the ``env`` dictionary returned by
:func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`.


Changing the Request
~~~~~~~~~~~~~~~~~~~~

@@ -692,6 +720,7 @@
   env['request'].route_url('verify', code='1337')
   # will return 'https://example.com/prefix/verify/1337'


Cleanup
~~~~~~~

@@ -706,6 +735,7 @@
   # .. do stuff ...

   env['closer']()


Setting Up Logging
~~~~~~~~~~~~~~~~~~
@@ -723,6 +753,7 @@
See :ref:`logging_chapter` for more information on logging within
:app:`Pyramid`.


.. index::
   single: console script


 docs/narr/project.rst

@@ -53,14 +53,18 @@
``alchemy``
  URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy`


.. index::
   single: creating a project
   single: project
   single: pcreate

.. _creating_a_project:

Creating the Project
--------------------

.. seealso:: See also the output of :ref:`pcreate --help <pcreate_script>`.

In :ref:`installing_chapter`, you created a virtual Python environment via the
``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use the
@@ -250,6 +254,8 @@
Running the Project Application
-------------------------------

.. seealso:: See also the output of :ref:`pserve --help <pserve_script>`.

Once a project is installed for development, you can run the application it
represents using the ``pserve`` command against the generated configuration
file.  In our case, this file is named ``development.ini``.

 docs/pscripts/index.rst

New file
@@ -0,0 +1,12 @@
.. _pscripts_documentation:

``p*`` Scripts Documentation
============================

``p*`` scripts included with :app:`Pyramid`:.

.. toctree::
   :maxdepth: 1
   :glob:

   *

 docs/pscripts/pcreate.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: pcreate; --help

.. _pcreate_script:

``pcreate``
-----------

.. program-output:: pcreate --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`creating_a_project`

 docs/pscripts/pdistreport.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: pdistreport; --help

.. _pdistreport_script:

``pdistreport``
---------------

.. program-output:: pdistreport --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`showing_distributions`

 docs/pscripts/prequest.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: prequest; --help

.. _prequest_script:

``prequest``
------------

.. program-output:: prequest --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`invoking_a_request`

 docs/pscripts/proutes.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: proutes; --help

.. _proutes_script:

``proutes``
-----------

.. program-output:: proutes --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`displaying_application_routes`

 docs/pscripts/pserve.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: pserve; --help

.. _pserve_script:

``pserve``
----------

.. program-output:: pserve --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`running_the_project_application`

 docs/pscripts/pshell.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: pshell; --help

.. _pshell_script:

``pshell``
----------

.. program-output:: pshell --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`interactive_shell`

 docs/pscripts/ptweens.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: ptweens; --help

.. _ptweens_script:

``ptweens``
-----------

.. program-output:: ptweens --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`displaying_tweens`

 docs/pscripts/pviews.rst

New file
@@ -0,0 +1,14 @@
.. index::
   single: pviews; --help

.. _pviews_script:

``pviews``
----------

.. program-output:: pviews --help
   :cwd: ../../env/bin
   :prompt:
   :shell:

.. seealso:: :ref:`displaying_matching_views`