Excise make_app from docs.

6 files changed, 55 insertions, 30 deletions

diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index aec605a84..7163eff71 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -50,7 +50,7 @@ application-specific configuration settings.
 |                                 |                             |  the :term:`application registry`      |
 |                                 |                             |  instead of the filename implied by    |
 |                                 |                             |  ``filename`` value passed to          |
-|                                 |                             |  ``repoze.bfg.router.make_app``.  If   |
+|                                 |                             |   ``repoze.bfg.router.make_app``.  If  |
 |                                 |                             |  this is a relative filename, it will  |
 |                                 |                             |  be considered relative to the         |
 |                                 |                             |  ``package`` passed to ``make_app``    |
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index e0b5ea542..f04e7f3ba 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -122,10 +122,9 @@ When the view attached to this route is invoked, :mod:`repoze.bfg`
 will attempt to use :term:`traversal` against the context implied by
 the :term:`root factory` of this route.  The above example isn't very
 useful unless you've defined a custom :term:`root factory` by passing
-it to the ``repoze.bfg.router.make_app`` function, because the
-*default* root factory cannot be traversed (it has no useful
-``__getitem__`` method).  But let's imagine that your root factory
-looks like so:
+it to constructor of a :term:`Configurator` because the *default* root
+factory cannot be traversed (it has no useful ``__getitem__`` method).
+But let's imagine that your root factory looks like so:
 
 .. code-block:: python
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 271dac897..18e63b474 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -220,10 +220,10 @@ the name ``main`` as a section name:
     >>> root
     <foo.models.MyModel object at 0x445270>
 
-... note:: You *might* get away without passing
-           ``--plugin=repoze.bfg`` to the bfgshell command; the
-           ``--plugin=repoze.bfg`` option is only required under
-           conditions that are not yet well-understood.
+.. note:: You *might* get away without passing
+          ``--plugin=repoze.bfg`` to the bfgshell command; the
+          ``--plugin=repoze.bfg`` option is only required under
+          conditions that are not yet well-understood.
 
 If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_
 installed in the interpreter you use to invoke the ``paster`` command,
@@ -242,10 +242,36 @@ Press "Ctrl-D" to exit the interactive shell.
 
 You should always use a section name argument that refers to the
 actual ``app`` section within the Paste configuration file that points
-at your BFG application *without any middleware wrapping*.  In
-particular, a section name is inappropriate as the second argument to
-"bfgshell" if the configuration section it names is a ``pipeline``
-rather than an ``app``.
+at your :mod:`repoze.bfg` application *without any middleware
+wrapping*.  In particular, a section name is inappropriate as the
+second argument to "bfgshell" if the configuration section it names is
+a ``pipeline`` rather than an ``app``.  For example, if you have the
+following ``.ini`` file content:
+
+.. code-block:: ini
+   :linenos:
+
+   [app:myapp]
+   use = egg:MyProject#app
+   reload_templates = true
+   debug_authorization = false
+   debug_notfound = false
+
+   [pipeline:main]
+   pipeline = egg:repoze.tm2#tm
+              myapp
+
+The command you use to invoke the interactive shell should be:
+
+.. code-block::  bash
+   :linenos:
+
+    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp
+
+If you use ``main`` as the section name argument instead of ``myapp``
+against the above ``.ini`` file, an error will likely occur.  Use the
+most specific reference to the application within the ``.ini`` file
+possible as the section name argument.
 
 Runnning The Project Application
 --------------------------------
@@ -372,8 +398,8 @@ shared by all the applications, servers and :term:`middleware` defined
 within the configuration file.  By default it contains one key
 ``debug``, which is set to ``true``.  This key is used by various
 components to decide whether to act in a "debugging" mode.
-``repoze.bfg`` itself does not do anything with this parameter as of
-this writing, and neither does the generated sample application.
+``repoze.bfg`` itself does not do anything at all with this parameter,
+and neither does any generated sample application.
 
 The ``[app:main]`` section represents configuration for your
 application.  This section name represents the ``main`` application
@@ -563,8 +589,8 @@ particular way.
 ``configure.zcml``
 ~~~~~~~~~~~~~~~~~~
 
-The ``configure.zcml`` represents the :term:`application
-registry`. It looks like so:
+The ``configure.zcml`` contains configuration statements that inform
+the :term:`application registry`. It looks like so:
 
 .. literalinclude:: MyProject/myproject/configure.zcml
    :linenos:
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index 7382c07ae..3871e154e 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -43,10 +43,10 @@ processing?
    :term:`route` named a ``factory`` argument, this factory is used to
    generate the root object, otherwise a default :term:`root factory`
    is used.  If a root factory argument was passed to the
-   ``repoze.bfg.router.make_app``, that callable is used to generate
-   the root object.  If the root factory argument passed to
-   ``make_app`` is ``None``, a default root factory is used to
-   generate a root.
+   :term:`Configurator` constructor, that callable is used to generate
+   the root object.  If the root factory argument passed to the
+   Configurator constructor is ``None``, a default root factory is
+   used to generate a root.
 
 #. A ``NewRequest`` :term:`event` is sent to any subscribers.
 
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 9802ec01e..a1c906c3b 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -29,7 +29,7 @@ return an object which represents the root of the object graph.  All
 usually a *mapping* object (such as a Python dictionary).
 
 .. note:: If a :term:`root factory` is passed to the :mod:`repoze.bfg`
-   "make_app" function as the value ``None``, a default root factory
+   :term:`Configurator` as the value ``None``, a default root factory
    is used.  This is most useful when you're using :term:`URL
    dispatch` and you don't care very much about traversing any
    particular graph to resolve URLs to code.  It is also possible to
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 33754e05b..ad0388284 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -41,13 +41,13 @@ before traversal has a chance to find it first.  If a route matches, a
 :term:`context` is generated and :mod:`repoze.bfg` will call the
 :term:`view` specified with the context and the request.  If no route
 matches, :mod:`repoze.bfg` will fail over to calling the :term:`root
-factory` callable passed to the application in it's ``make_app``
-function (usually a traversal function).
+factory` callable passed to the :term:`Configurator` for the
+application (usually a traversal function).
 
 A root factory is not required for purely URL-dispatch-based apps: if
-the root factory callable is passed as ``None`` to the ``make_app``
-function, :mod:`repoze.bfg` will return a ``NotFound`` error to the user's
-browser when no routes match.
+the root factory callable is passed as ``None`` to the
+:term:`Configurator`, :mod:`repoze.bfg` will return a ``NotFound``
+error to the user's browser when no routes match.
 
 .. note:: See :ref:`modelspy_project_section` for an example of a
           simple root factory callable that will use traversal.
@@ -497,9 +497,9 @@ class that accepts a request in its ``__init__``.
    type.
 
 If no route matches in the above configuration, :mod:`repoze.bfg` will
-call the "fallback" :term:`root factory` callable provided to it
-during ``make_app`.  If the "fallback" root factory is None, a
-``NotFound`` error will be raised when no route matches.
+call the "fallback" :term:`root factory` callable provided to the
+:term:`Configurator` constructor.  If the "fallback" root factory is
+None, a ``NotFound`` error will be raised when no route matches.
 
 .. note:: See :ref:`using_model_interfaces` for more information about
           how views are found when interfaces are attached to a