- Updated paster template "ez_setup.py" to one that requires

    setuptools 0.6c9.

  - Turn ``view_execution_permitted`` from the :mod:`repoze.bfg.view`
    module into a documented API.

  - Doc cleanups.

7 files changed, 40 insertions, 25 deletions

diff --git a/docs/narr/MyProject/MyProject.ini b/docs/narr/MyProject/MyProject.ini
index c1ff50547..f5d094dff 100644
--- a/docs/narr/MyProject/MyProject.ini
+++ b/docs/narr/MyProject/MyProject.ini
@@ -5,6 +5,7 @@ debug = true
 use = egg:MyProject#app
 reload_templates = true
 debug_authorization = false
+debug_notfound = false
 
 [server:main]
 use = egg:Paste#http
diff --git a/docs/narr/MyProject/ez_setup.py b/docs/narr/MyProject/ez_setup.py
index 89cf056d9..d24e845e5 100644
--- a/docs/narr/MyProject/ez_setup.py
+++ b/docs/narr/MyProject/ez_setup.py
@@ -14,7 +14,7 @@ the appropriate options to ``use_setuptools()``.
 This file can also be run as a script to install or upgrade setuptools.
 """
 import sys
-DEFAULT_VERSION = "0.6c8"
+DEFAULT_VERSION = "0.6c9"
 DEFAULT_URL     = "http://pypi.python.org/packages/%s/s/setuptools/" % sys.version[:3]
 
 md5_data = {
@@ -48,13 +48,18 @@ md5_data = {
     'setuptools-0.6c8-py2.3.egg': '50759d29b349db8cfd807ba8303f1902',
     'setuptools-0.6c8-py2.4.egg': 'cba38d74f7d483c06e9daa6070cce6de',
     'setuptools-0.6c8-py2.5.egg': '1721747ee329dc150590a58b3e1ac95b',
+    'setuptools-0.6c9-py2.3.egg': 'a83c4020414807b496e4cfbe08507c03',
+    'setuptools-0.6c9-py2.4.egg': '260a2be2e5388d66bdaee06abec6342a',
+    'setuptools-0.6c9-py2.5.egg': 'fe67c3e5a17b12c0e7c541b7ea43a8e6',
+    'setuptools-0.6c9-py2.6.egg': 'ca37b1ff16fa2ede6e19383e7b59245a',
 }
 
 import sys, os
+try: from hashlib import md5
+except ImportError: from md5 import md5
 
 def _validate_md5(egg_name, data):
     if egg_name in md5_data:
-        from md5 import md5
         digest = md5(data).hexdigest()
         if digest != md5_data[egg_name]:
             print >>sys.stderr, (
@@ -64,7 +69,6 @@ def _validate_md5(egg_name, data):
             sys.exit(2)
     return data
 
-
 def use_setuptools(
     version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir,
     download_delay=15
@@ -233,7 +237,6 @@ def update_md5(filenames):
     """Update our built-in md5 registry"""
 
     import re
-    from md5 import md5
 
     for name in filenames:
         base = os.path.basename(name)
@@ -270,3 +273,4 @@ if __name__=='__main__':
 
 
 
+
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 57ce8a700..2eb391ce3 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -8,9 +8,10 @@ How To Install
 
 You will need `Python <http://python.org>`_ version 2.4 or better to
 run :mod:`repoze.bfg`.  It has been tested under Python 2.4.5, Python
-2.5.2 and Python 2.6.  Development of :mod:`repoze.bfg` is done
-primarily under Python 2.4.  :mod:`repoze.bfg` does *not* run under
-any version of Python before 2.4, and does *not* run under Python 3.X.
+2.5.2 and Python 2.6.  Development of :mod:`repoze.bfg` is currently
+done primarily under Python 2.4.  :mod:`repoze.bfg` does *not* run
+under any version of Python before 2.4, and does *not* run under
+Python 3.X.
 
 .. warning:: To succesfully install :mod:`repoze.bfg`, you will need
    an environment capable of compiling C code.  See the documentation
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 3f9b7d09a..7f8bcec35 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -24,7 +24,10 @@ developer rather than the application developer.  :mod:`repoze.bfg`
 developers use :term:`ZCML` (an XML dialect) to perform various
 configuration tasks; in particular, as in Zope3, one more more
 :term:`view` functions is associated with a :term:`model` type via
-ZCML.
+ZCML.  It is also possible to configure :mod:`repoze.bfg` views
+without :term:`ZCML` (instead configuration is done inside Python
+decorators) by using an add-on package named
+:term:`repoze.bfg.convention`.
 
 Like Pylons, :mod:`repoze.bfg` is mostly policy-free.  It makes no
 assertions about which database you should use, and its built-in
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 194c168c3..ad74fb8e0 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -332,6 +332,10 @@ changes will not require an application restart to be detected.  See
    production applications, as template rendering is slowed when it is
    turned on.
 
+Various other settings may exist in this section having to do with
+debugging a :mod:`repoze.bfg` application.  See
+:ref:`environment_chapter` for more information about these settings.
+
 The ``[server:main]`` section of the configuration file configures a
 WSGI server which listens on port 6543.  It is configured to listen on
 all interfaces (``0.0.0.0``).  The ``Paste#http`` server will create a
@@ -392,7 +396,7 @@ that should point at your application project's URL (if any).
 ``packages=find_packages()`` causes all packages within the project to
 be found when packaging the application.  ``include_package_data``
 will include non-Python files when the application is packaged (if
-those files are checked into version control).  ``zip_safe` indicates
+those files are checked into version control).  ``zip_safe`` indicates
 that this package is not safe to ship as a zipped egg (it will unpack
 as a directory, which is more convenient).  ``install_requires`` and
 ``tests_require`` indicate that this package depends on the
@@ -468,8 +472,9 @@ registry`. It looks like so:
    :language: xml
 
 #. Lines 1-3 provide the root node and namespaces for the
-   configuration language.  ``bfg`` is the namespace for
-   :mod:`repoze.bfg` -specific configuration directives.
+   configuration language.  ``http://namespaces.repoze.org/bfg`` is
+   the default XML namespace.  Add-on packages may require other
+   namespaces.
 
 #. Line 6 initializes :mod:`repoze.bfg`-specific configuration
    directives by including the ``repoze.bfg.includes`` package.  This
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index b9391b273..e12f0ef81 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -90,7 +90,8 @@ press ``return`` after running ``paster serve MyProject.ini``.
    entry point URI ``egg:MyProject#app`` (see :ref:`MyProject_ini` for
    more information about entry point URIs, and how they relate to
    callables), will receive the key/value pairs
-   ``{'reload_templates':'true'}``.
+   ``{'reload_templates':'true', 'debug_authorization':'false',
+   'debug_notfound':'false'}``.
 
 #. The constructor itself is invoked.  A generated :mod:`repoze.bfg`
    ``app`` function will look like the below.
@@ -109,14 +110,14 @@ press ``return`` after running ``paster serve MyProject.ini``.
    package which allows the user to pass framework-related (as opposed
    to application-related) options to an application constructor.  It
    picks off framework-related options from the ``**kw`` dictionary
-   passed in to the constructor.  We actually use a framework option
-   named ``reload_templates`` in our configuration.  Note that we make
-   no use of this option in our application, but the fact that we use
-   ``get_options`` to parse the ``*kw`` dict, and subsequently pass
-   along the result as the ``options`` argument to ``make_app``.
-   ``reload_templates`` has special meaning to the framework: if it's
-   ``true``, we will cause templates to be automatically reloaded by
-   the application when they are changed.
+   passed in to the constructor.  For example, we actually use a
+   framework option named ``reload_templates`` in our configuration.
+   Note that we make no use of this option in our application, but the
+   fact that we use ``get_options`` to parse the ``*kw`` dict, and
+   subsequently pass along the result as the ``options`` argument to
+   ``make_app``.  ``reload_templates`` has special meaning to the
+   framework: if it's ``true``, we will cause templates to be
+   automatically reloaded by the application when they are changed.
 
    ``get_root`` is the first argument to ``make_app``, and it is a
    callable that is invoked on every request to retrieve the
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 48a9ac52e..fcddb55dd 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -13,7 +13,7 @@ its default and best-supported templating language. However,
 :mod:`repoze.bfg` uses a different implementation of the :term:`ZPT`
 specification than Zope does: the :term:`Chameleon`
 :term:`chameleon.zpt` templating engine. This templating engine
-complies with the `Zope Page Template
+complies largely with the `Zope Page Template
 <http://wiki.zope.org/ZPT/FrontPage>`_ template specification and is
 significantly faster.
 
@@ -27,7 +27,7 @@ significantly faster.
    :mod:`repoze.bfg`.
 
 Given that there is a :term:`chameleon.zpt` template named
-``foo.html`` in a directory in your application named ``templates``,
+``foo.pt`` in a directory in your application named ``templates``,
 you can render the template from a view like so:
 
 .. code-block:: python
@@ -35,12 +35,12 @@ you can render the template from a view like so:
 
    from repoze.bfg.chameleon_zpt import render_template_to_response
    def sample_view(context, request):
-       return render_template_to_response('templates/foo.html', foo=1, bar=2)
+       return render_template_to_response('templates/foo.pt', foo=1, bar=2)
 
 The first argument to ``render_template_to_response`` shown above (and
 its sister function ``render_template``, not shown, which just returns
 a string body) is the template *path*.  Above, the path
-``templates/foo.html`` is *relative*.  Relative to what, you ask?
+``templates/foo.pt`` is *relative*.  Relative to what, you ask?
 Relative to the directory in which the ``views.py`` file which names
 it lives, which is usually the :mod:`repoze.bfg` application's
 :term:`package` directory.
@@ -59,7 +59,7 @@ string manually as a response body:
    from repoze.bfg.chameleon_zpt import render_template
    from webob import Response
    def sample_view(context, request):
-       result = render_template('templates/foo.html', foo=1, bar=2)
+       result = render_template('templates/foo.pt', foo=1, bar=2)
        response = Response(result)
        response.content_type = 'text/plain'
        return response