Zero in on making docs render properly.

5 files changed, 23 insertions, 32 deletions

diff --git a/docs/modules/router.rst b/docs/modules/router.rst
index 435a7ebd0..84d51f73a 100644
--- a/docs/modules/router.rst
+++ b/docs/modules/router.rst
@@ -5,9 +5,6 @@
 
 .. automodule:: repoze.bfg.router
 
-    :class:`Router`
-    ===================
-
-    .. autoclass:: Router
+.. autoclass:: Router
 
 .. autofunction:: repoze.bfg.router.make_app
diff --git a/docs/modules/security.rst b/docs/modules/security.rst
index 0a692e521..317a7b335 100644
--- a/docs/modules/security.rst
+++ b/docs/modules/security.rst
@@ -32,22 +32,12 @@
     'george', 'read')`` that means deny access.  A sequence of ACEs
     makes up an ACL.  It is a string, and it's actual value is "Deny".
 
-  :class:`RemoteUserACLSecurityPolicy`
-  ------------------------------------
-
   .. autoclass:: RemoteUserACLSecurityPolicy
-
-     .. automethod:: permits
-
-  :class:`Denied`
-  ===============
+     :members:
 
   .. autoclass:: Denied
      :members:
 
-  :class:`Allowed`
-  ================
-
   .. autoclass:: Allowed
      :members:
 
diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index e9e0f175a..9dd590fc0 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -58,7 +58,8 @@ def make_app(root_policy, package=None, filename='configure.zcml'):
     application.  'root_policy' must be a callable that accepts an
     environ and returns a graph root object.  'package' is the
     dotted-Python-path packagename of the application, 'filename' is
-    the ZCML file that should be parsed to create the view registry."""
+    the ZCML file (relative to the package path) that should be parsed
+    to create the view registry."""
     from repoze.bfg.registry import makeRegistry
     registry = makeRegistry(filename, package)
     return Router(root_policy, registry)
diff --git a/repoze/bfg/security.py b/repoze/bfg/security.py
index 6ee2d7d95..9ed3db538 100644
--- a/repoze/bfg/security.py
+++ b/repoze/bfg/security.py
@@ -15,12 +15,13 @@ Deny = 'Deny'
 
 def has_permission(permission, context, request):
     """ Provided a permission (a string or unicode object), a context
-    (a model instance) and a request object, return ``Allowed`` if the
-    permission is granted in this context to the user implied by the
-    request. Return ``Denied`` if this permission is not granted in
-    this context to this user.  This delegates to the current security
-    policy.  Return True unconditionally if no security policy has
-    been configured in this application."""
+    (a model instance) and a request object, return an instance of
+    ``Allowed`` if the permission is granted in this context to the
+    user implied by the request. Return an instance of ``Denied`` if
+    this permission is not granted in this context to this user.  This
+    delegates to the current security policy.  Return True
+    unconditionally if no security policy has been configured in this
+    application."""
     policy = queryUtility(ISecurityPolicy)
     if policy is None:
         return True
@@ -120,11 +121,11 @@ class PermitsResult:
         return msg
 
 class Denied(PermitsResult):
-    """ The value type returned by an ACL denial.  It evaluates equal
-    to all boolean false types.  It also has attributes which indicate
-    which acl, ace, permission, principals, and context were involved
-    in the request.  Its __str__ method prints a summary of these
-    attributes for debugging purposes. """
+    """ An instance of ``Denied`` is returned by an ACL denial.  It
+    evaluates equal to all boolean false types.  It also has
+    attributes which indicate which acl, ace, permission, principals,
+    and context were involved in the request.  Its __str__ method
+    prints a summary of these attributes for debugging purposes."""
     def __nonzero__(self):
         return False
 
@@ -133,11 +134,11 @@ class Denied(PermitsResult):
             return True
 
 class Allowed(PermitsResult):
-    """ The value type returned by an ACL denial.  It evaluates equal
-    to all boolean true types.  It also has attributes which indicate
-    which acl, ace, permission, principals, and context were involved
-    in the request.  Its __str__ method prints a summary of these
-    attributes for debugging purposes. """
+    """ An instance of ``Allowed`` is returned by an ACL allow.  It
+    evaluates equal to all boolean true types.  It also has attributes
+    which indicate which acl, ace, permission, principals, and context
+    were involved in the request.  Its __str__ method prints a summary
+    of these attributes for debugging purposes."""
     def __nonzero__(self):
         return True
 
diff --git a/setup.py b/setup.py
index 48f250502..1a8312131 100644
--- a/setup.py
+++ b/setup.py
@@ -66,6 +66,8 @@ setup(name='repoze.bfg',
             'Paste',
             'z3c.pt',
             'FormEncode',
+            'Sphinx',
+            'docutils',
             ],
       test_suite="repoze.bfg.tests",
       entry_points = """\