Merge pull request #2191 from stevepiercy/master

add p* scripts output for --help

16 files changed, 178 insertions, 5 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 32c4995b8..77f5d94ac 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -301,6 +301,9 @@ Docs
   ``principal`` and a ``userid`` in its security APIs.
   See https://github.com/Pylons/pyramid/pull/1399
 
+- Add documentation of command line programs (``p*`` scripts). See
+  https://github.com/Pylons/pyramid/pull/2191
+
 Scaffolds
 ---------
 
diff --git a/docs/conf.py b/docs/conf.py
index 8a9bac6ed..073811eca 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,12 +53,13 @@ extensions = [
     'sphinx.ext.doctest',
     'repoze.sphinx.autointerface',
     'sphinx.ext.viewcode',
-    'sphinx.ext.intersphinx'
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib.programoutput',
     ]
 
 # Looks for objects in external projects
 intersphinx_mapping = {
-    'colander': (        'http://docs.pylonsproject.org/projects/colander/en/latest', None),
+    'colander': ('http://docs.pylonsproject.org/projects/colander/en/latest', None),
     'cookbook': ('http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/', None),
     'deform': ('http://docs.pylonsproject.org/projects/deform/en/latest', None),
     'jinja2': ('http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
@@ -66,8 +67,8 @@ intersphinx_mapping = {
     'python': ('http://docs.python.org', None),
     'python3': ('http://docs.python.org/3', None),
     'sqla': ('http://docs.sqlalchemy.org/en/latest', None),
-    'tm': ('http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/',         None),
-    'toolbar':         ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None),
+    'tm': ('http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/', None),
+    'toolbar': ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None),
     'tstring': ('http://docs.pylonsproject.org/projects/translationstring/en/latest', None),
     'tutorials': ('http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/', None),
     'venusian': ('http://docs.pylonsproject.org/projects/venusian/en/latest', None),
diff --git a/docs/index.rst b/docs/index.rst
index e792b9905..8c8a0a18d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -162,6 +162,19 @@ Comprehensive reference material for every public API exposed by
    api/*
 
 
+``p*`` Scripts Documentation
+============================
+
+``p*`` scripts included with :app:`Pyramid`:.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   pscripts/index
+   pscripts/*
+
+
 Change History
 ==============
 
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index eb79dffb6..34b12e1e9 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -6,6 +6,7 @@ Command-Line Pyramid
 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
@@ -15,6 +16,8 @@ of command-line utilities.  These utilities are documented in this chapter.
 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.
 You can use the ``pviews`` command in a terminal window to print a summary of
@@ -114,6 +117,8 @@ found* message.
 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
@@ -179,6 +184,7 @@ hash after the filename:
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
+
 .. index::
    pair: pshell; extending
 
@@ -261,6 +267,7 @@ request is configured to generate urls from the host
     >>> request.route_url('home')
     'https://www.example.com/'
 
+
 .. _ipython_or_bpython:
 
 Alternative Shells
@@ -317,6 +324,7 @@ arguments, ``env`` and ``help``, which would look like this:
    ``ipython`` and ``bpython`` have been moved into their respective
    packages ``pyramid_ipython`` and ``pyramid_bpython``.
 
+
 Setting a Default Shell
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -331,6 +339,7 @@ specify a list of preferred shells.
 
 .. versionadded:: 1.6
 
+
 .. index::
    pair: routes; printing
    single: proutes
@@ -340,6 +349,8 @@ specify a list of preferred shells.
 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
 :ref:`interactive_shell`), the ``proutes`` command accepts one argument with
@@ -421,6 +432,8 @@ include. The current available formats are ``name``, ``pattern``, ``view``, and
 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
@@ -497,6 +510,7 @@ used:
 
 See :ref:`registering_tweens` for more information about tweens.
 
+
 .. index::
    single: invoking a request
    single: prequest
@@ -506,6 +520,8 @@ See :ref:`registering_tweens` for more information about tweens.
 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.
 
@@ -555,6 +571,7 @@ of the ``prequest`` process is used as the ``POST`` body::
 
    $ $VENV/bin/prequest -mPOST development.ini / < somefile
 
+
 Using Custom Arguments to Python when Running ``p*`` Scripts
 ------------------------------------------------------------
 
@@ -566,11 +583,22 @@ Python interpreter at runtime. For example::
 
       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
 distributions in your Python environment::
@@ -590,6 +618,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:
 
 Writing a Script
@@ -702,6 +731,7 @@ The above example specifies the ``another`` ``app``, ``pipeline``, or
 object present in the ``env`` dictionary returned by
 :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`.
 
+
 Changing the Request
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -742,6 +772,7 @@ Now you can readily use Pyramid's APIs for generating URLs:
    env['request'].route_url('verify', code='1337')
    # will return 'https://example.com/prefix/verify/1337'
 
+
 Cleanup
 ~~~~~~~
 
@@ -757,6 +788,7 @@ callback:
 
    env['closer']()
 
+
 Setting Up Logging
 ~~~~~~~~~~~~~~~~~~
 
@@ -773,6 +805,7 @@ use the following command:
 See :ref:`logging_chapter` for more information on logging within
 :app:`Pyramid`.
 
+
 .. index::
    single: console script
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4785b60c4..5103bb6b8 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -53,15 +53,19 @@ The included scaffolds are these:
 ``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
 ``pcreate`` command installed within the virtualenv.  We'll choose the
@@ -262,6 +266,8 @@ single sample test exists.
 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``.
diff --git a/docs/pscripts/index.rst b/docs/pscripts/index.rst
new file mode 100644
index 000000000..857e0564f
--- /dev/null
+++ b/docs/pscripts/index.rst
@@ -0,0 +1,12 @@
+.. _pscripts_documentation:
+
+``p*`` Scripts Documentation
+============================
+
+Command line programs (``p*`` scripts) included with :app:`Pyramid`.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/docs/pscripts/pcreate.rst b/docs/pscripts/pcreate.rst
new file mode 100644
index 000000000..b5ec3f4e2
--- /dev/null
+++ b/docs/pscripts/pcreate.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: pcreate; --help
+
+.. _pcreate_script:
+
+``pcreate``
+-----------
+
+.. program-output:: pcreate --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`creating_a_project`
diff --git a/docs/pscripts/pdistreport.rst b/docs/pscripts/pdistreport.rst
new file mode 100644
index 000000000..1c53fb6e9
--- /dev/null
+++ b/docs/pscripts/pdistreport.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: pdistreport; --help
+
+.. _pdistreport_script:
+
+``pdistreport``
+---------------
+
+.. program-output:: pdistreport --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`showing_distributions`
diff --git a/docs/pscripts/prequest.rst b/docs/pscripts/prequest.rst
new file mode 100644
index 000000000..a15827767
--- /dev/null
+++ b/docs/pscripts/prequest.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: prequest; --help
+
+.. _prequest_script:
+
+``prequest``
+------------
+
+.. program-output:: prequest --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`invoking_a_request`
diff --git a/docs/pscripts/proutes.rst b/docs/pscripts/proutes.rst
new file mode 100644
index 000000000..09ed013e1
--- /dev/null
+++ b/docs/pscripts/proutes.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: proutes; --help
+
+.. _proutes_script:
+
+``proutes``
+-----------
+
+.. program-output:: proutes --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`displaying_application_routes`
diff --git a/docs/pscripts/pserve.rst b/docs/pscripts/pserve.rst
new file mode 100644
index 000000000..d33d4a484
--- /dev/null
+++ b/docs/pscripts/pserve.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: pserve; --help
+
+.. _pserve_script:
+
+``pserve``
+----------
+
+.. program-output:: pserve --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`running_the_project_application`
diff --git a/docs/pscripts/pshell.rst b/docs/pscripts/pshell.rst
new file mode 100644
index 000000000..cfd84d4f8
--- /dev/null
+++ b/docs/pscripts/pshell.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: pshell; --help
+
+.. _pshell_script:
+
+``pshell``
+----------
+
+.. program-output:: pshell --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`interactive_shell`
diff --git a/docs/pscripts/ptweens.rst b/docs/pscripts/ptweens.rst
new file mode 100644
index 000000000..02e23e49a
--- /dev/null
+++ b/docs/pscripts/ptweens.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: ptweens; --help
+
+.. _ptweens_script:
+
+``ptweens``
+-----------
+
+.. program-output:: ptweens --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`displaying_tweens`
diff --git a/docs/pscripts/pviews.rst b/docs/pscripts/pviews.rst
new file mode 100644
index 000000000..b4de5c054
--- /dev/null
+++ b/docs/pscripts/pviews.rst
@@ -0,0 +1,13 @@
+.. index::
+   single: pviews; --help
+
+.. _pviews_script:
+
+``pviews``
+----------
+
+.. program-output:: pviews --help
+   :prompt:
+   :shell:
+
+.. seealso:: :ref:`displaying_matching_views`
diff --git a/pyramid/scripts/prequest.py b/pyramid/scripts/prequest.py
index 61e422c64..e07f9d10e 100644
--- a/pyramid/scripts/prequest.py
+++ b/pyramid/scripts/prequest.py
@@ -14,7 +14,7 @@ def main(argv=sys.argv, quiet=False):
 
 class PRequestCommand(object):
     description = """\
-    Run a request for the described application.
+    Submit a HTTP request to a web application.
 
     This command makes an artifical request to a web application that uses a
     PasteDeploy (.ini) configuration file for the server and application.
diff --git a/setup.py b/setup.py
index c81956e7f..9bdfcd90e 100644
--- a/setup.py
+++ b/setup.py
@@ -61,6 +61,7 @@ docs_extras = [
     'repoze.sphinx.autointerface',
     'pylons_sphinx_latesturl',
     'pylons-sphinx-themes',
+    'sphinxcontrib-programoutput',
     ]
 
 testing_extras = tests_require + [