move all paster commands to a separate chapter

1 files changed, 11 insertions, 137 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4a7f63176..4b08d09f6 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -194,7 +194,8 @@ Elided output from a run of this command is shown below:
 
 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
-:term:`PasteDeploy` commands such as ``paster serve`` and ``paster pshell``.
+:term:`PasteDeploy` commands such as ``paster serve``, ``paster pshell``,
+``paster proutes`` and ``paster pviews``.
 
 .. index::
    single: running tests
@@ -244,142 +245,6 @@ create`` -generated project.  Within a project generated by the
 ``pyramid_starter`` scaffold, a single sample test exists.
 
 .. index::
-   single: interactive shell
-   single: IPython
-   single: paster pshell
-
-.. _interactive_shell:
-
-The Interactive Shell
----------------------
-
-Once you've installed your program for development using ``setup.py
-develop``, you can use an interactive Python shell to examine your
-:app:`Pyramid` project's :term:`resource` and :term:`view` objects from a
-Python prompt.  To do so, use your virtualenv's ``paster pshell`` command.
-
-The argument to ``pshell`` follows the format ``config_file#section_name``
-where ``config_file`` is the path to your application's ``.ini`` file and
-``section_name`` is the ``app`` section name inside the ``.ini`` file which
-points to *your application* as opposed to any other section within the
-``.ini`` file.  For example, if your application ``.ini`` file might have a
-``[app:MyProject]`` section that looks like so:
-
-.. code-block:: ini
-   :linenos:
-
-   [app:MyProject]
-   use = egg:MyProject
-   reload_templates = true
-   debug_authorization = false
-   debug_notfound = false
-   debug_templates = true
-   default_locale_name = en
-
-If so, you can use the following command to invoke a debug shell using the
-name ``MyProject`` as a section name:
-
-.. code-block:: text
-
-   [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini#MyProject
-   Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
-   [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
-
-   Default Variables:
-     app          The WSGI Application
-     root         The root of the default resource tree.
-     registry     The Pyramid registry object.
-     settings     The Pyramid settings object.
-
-   >>> root
-   <myproject.resources.MyResource object at 0x445270>
-   >>> registry
-   <Registry myproject>
-   >>> settings['debug_notfound']
-   False
-   >>> from myproject.views import my_view
-   >>> from pyramid.request import Request
-   >>> r = Request.blank('/')
-   >>> my_view(r)
-   {'project': 'myproject'}
-
-The WSGI application that is loaded will be available in the shell as the
-``app`` global. Also, if the application that is loaded is the
-:app:`Pyramid` app with no surrounding middleware, the ``root`` object
-returned by the default :term:`root factory`, ``registry``, and ``settings``
-will be available.
-
-The interactive shell will not be able to load some of the globals like
-``root``, ``registry`` and ``settings`` if the section name specified when
-loading ``pshell`` is not referencing your :app:`Pyramid` application directly.
-For example, if you have the following ``.ini`` file content:
-
-.. code-block:: ini
-   :linenos:
-
-   [app:MyProject]
-   use = egg:MyProject
-   reload_templates = true
-   debug_authorization = false
-   debug_notfound = false
-   debug_templates = true
-   default_locale_name = en
-
-   [pipeline:main]
-   pipeline =
-       egg:WebError#evalerror
-       MyProject
-
-Use ``MyProject`` instead of ``main`` as the section name argument to
-``pshell`` against the above ``.ini`` file (e.g. ``paster pshell
-development.ini#MyProject``).
-
-Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
-
-.. _extending_pshell:
-
-Extending the Shell
-~~~~~~~~~~~~~~~~~~~
-
-It is sometimes convenient when using the interactive shell often to have
-some variables significant to your application already loaded as globals
-when you start the ``pshell``. To facilitate this, ``pshell`` will look
-for a special ``[pshell]`` section in your INI file and expose the subsequent
-key/value pairs to the shell.
-
-For example, you want to expose your model to the shell, along with the
-database session so that you can mutate the model on an actual database.
-Here, we'll assume your model is stored in the ``myapp.models`` package.
-
-.. code-block:: ini
-   :linenos:
-
-   [pshell]
-   m = myapp.models
-   session = myapp.models.DBSession
-   t = transaction
-
-When this INI file is loaded, the extra variables ``m``, ``session`` and
-``t`` will be available for use immediately. This happens regardless of
-whether the ``registry`` and other special variables are loaded.
-
-IPython
-~~~~~~~
-
-If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ installed in
-the interpreter you use to invoke the ``paster`` command, the ``pshell``
-command will use an IPython interactive shell instead of a standard Python
-interpreter shell.  If you don't want this to happen, even if you have
-IPython installed, you can pass the ``--disable-ipython`` flag to the
-``pshell`` command to use a standard Python interpreter shell
-unconditionally.
-
-.. code-block:: text
-
-   [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \
-                                development.ini#MyProject
-
-.. index::
    single: running an application
    single: paster serve
    single: reload
@@ -1067,4 +932,13 @@ This pattern can be used to rearrage code referred to by any Pyramid API
 argument which accepts a :term:`dotted Python name` or direct object
 reference.
 
+Using the Interactive Shell
+---------------------------
+
+It is possible to use a Python interpreter prompt loaded with a similar
+configuration as would be loaded if you were running your Pyramid application
+via ``paster serve``.  This can be a useful debugging tool.  See
+:ref:`interactive_shell` for more details.
+
+