cross-refs and cleanups for checker and adapter.

docs/api/adapter.rst

@@ -1,6 +1,5 @@
-:mod:`zope.security.adapter`
-============================
+=======================
+ zope.security.adapter
+=======================
 
 .. automodule:: zope.security.adapter
-   :members:
-   :member-order: bysource

docs/api/checker.rst

@@ -1,17 +1,25 @@
-:mod:`zope.security.checker`
-============================
+=======================
+ zope.security.checker
+=======================
+
+.. currentmodule:: zope.security.checker
+
+
+Module API Documentation
+========================
 
 .. automodule:: zope.security.checker
-   :members:
-   :member-order: bysource
 
 
+API Doctests
+============
+
 Protections for Modules
 -----------------------
 
-The :func:`zope.secuirty.checker.moduleChecker` API can be used to
-determine whether a module has been protected: Initially, there's no checker
-defined for the module:
+The :func:`moduleChecker` API can be used to determine whether a
+module has been protected: Initially, there's no checker defined for
+the module:
 
 .. doctest::
 
@@ -20,7 +28,9 @@ defined for the module:
    >>> moduleChecker(test_zcml_functest) is None
    True
 
-We can add a checker using :func:`zope.security.metaconfigure.protectModule`:
+We can add a checker using
+:func:`zope.security.metaconfigure.protectModule` (although this is
+more commonly done using ZCML):
 
 .. doctest::
 
@@ -202,26 +212,26 @@ Protections for standard objects
    ...         return 'ForbiddenAttribute: %s' % e.args[0]
 
 Rocks
-#####
+~~~~~
 
-Rocks are immuatle, non-callable objects without interesting methods.  They
+Rocks are immutable, non-callable objects without interesting methods.  They
 *don't* get proxied.
 
 .. doctest::
 
-   >>> type(ProxyFactory(  object()  )) is object
+   >>> type(ProxyFactory(object())) is object
    True
-   >>> type(ProxyFactory(  1  )) is int
+   >>> type(ProxyFactory(1)) is int
    True
-   >>> type(ProxyFactory(  1.0  )) is float
+   >>> type(ProxyFactory(1.0)) is float
    True
-   >>> type(ProxyFactory(  1j  )) is complex
+   >>> type(ProxyFactory(1j)) is complex
    True
-   >>> type(ProxyFactory(  None  )) is type(None)
+   >>> type(ProxyFactory(None)) is type(None)
    True
-   >>> type(ProxyFactory(  'xxx'  )) is str
+   >>> type(ProxyFactory('xxx')) is str
    True
-   >>> type(ProxyFactory(  True  )) is type(True)
+   >>> type(ProxyFactory(True)) is type(True)
    True
 
 Datetime-reltatd instances are rocks, too:
@@ -249,7 +259,7 @@ Datetime-reltatd instances are rocks, too:
 
 
 dicts
-#####
+~~~~~
 
 We can do everything we expect to be able to do with proxied dicts.
 
@@ -301,7 +311,7 @@ not checking that under python > 2):
     True
 
 lists
-#####
+~~~~~
 
 We can do everything we expect to be able to do with proxied lists.
 
@@ -357,7 +367,7 @@ Always available:
    True
 
 tuples
-######
+~~~~~~
 
 We can do everything we expect to be able to do with proxied tuples.
 
@@ -404,7 +414,7 @@ Always available:
    True
 
 sets
-####
+~~~~
 
 we can do everything we expect to be able to do with proxied sets.
 
@@ -576,7 +586,7 @@ with any kind of proxy.
 
 
 frozensets
-##########
+~~~~~~~~~~
 
 we can do everything we expect to be able to do with proxied frozensets.
 
@@ -754,7 +764,7 @@ with any kind of proxy.
    True
 
 iterators
-#########
+~~~~~~~~~
 
 .. doctest::
 
@@ -823,7 +833,7 @@ We shouldn't be able to iterate if we don't have an assertion:
 
 
 New-style classes
-#################
+~~~~~~~~~~~~~~~~~
 
 .. doctest::
 
@@ -859,7 +869,7 @@ Always available:
    True
 
 New-style Instances
-###################
+~~~~~~~~~~~~~~~~~~~
 
 .. doctest::
 
@@ -891,7 +901,7 @@ Always available:
 
 
 Classic Classes
-###############
+~~~~~~~~~~~~~~~
 
 .. doctest::
 
@@ -925,7 +935,7 @@ Always available:
    True
 
 Classic Instances
-#################
+~~~~~~~~~~~~~~~~~
 
 .. doctest::
 
@@ -955,7 +965,7 @@ Always available:
    True
 
 Interfaces and declarations
-###########################
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We can still use interfaces though proxies:
 
@@ -989,7 +999,7 @@ We can still use interfaces though proxies:
 
 
 abstract Base Classes
-#####################
+~~~~~~~~~~~~~~~~~~~~~
 
 We work with the ABCMeta meta class:
 

docs/api/interfaces.rst

@@ -1,5 +1,5 @@
-=================================
- :mod:`zope.security.interfaces`
-=================================
+==========================
+ zope.security.interfaces
+==========================
 
 .. automodule:: zope.security.interfaces

docs/api/metaconfigure.rst

@@ -0,0 +1,5 @@
+=============================
+ zope.security.metaconfigure
+=============================
+
+.. automodule:: zope.security.metaconfigure

docs/conf.py

@@ -263,6 +263,7 @@
     'https://zopeinterface.readthedocs.io/en/latest': None,
     'https://zopeproxy.readthedocs.io/en/latest': None,
     'https://zopeschema.readthedocs.io/en/latest': None,
+    'https://zopelocation.readthedocs.io/en/latest': None,
 }
 
 extlinks = {'issue': ('https://github.com/zopefoundation/zope.datetime/issues/%s',

docs/index.rst

@@ -1,8 +1,9 @@
-:mod:`zope.security` Documentation
-==================================
+====================================
+ ``zope.security`` Documentation
+====================================
 
 Narrative Documentation
------------------------
+=======================
 
 .. toctree::
    :maxdepth: 2
@@ -11,7 +12,7 @@ Narrative Documentation
    hacking
 
 API Reference
--------------
+=============
 
 .. toctree::
    :maxdepth: 2
@@ -26,13 +27,14 @@ API Reference
    api/proxy
    api/simplepolicies
    api/testing
+   api/metaconfigure
    api/zcml
 
 
-Indices and tables
-==================
+====================
+ Indices and tables
+====================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

src/zope/security/adapter.py

@@ -19,12 +19,13 @@
 from zope.location import ILocation, LocationProxy
 
 def assertLocation(adapter, parent):
-    """Assert locatable adapters.
+    """
+    Assert locatable adapters.
 
-    This function asserts that the adapter get location-proxied if
-    it doesn't provide ILocation itself. Further more the returned
-    locatable adapter get its parent set if its __parent__ attribute
-    is currently None.
+    This function asserts that the adapter get location-proxied if it
+    doesn't provide :class:`zope.location.interfaces.ILocation`
+    itself. Furthermore, the returned locatable adapter get its parent
+    set if its ``__parent__`` attribute is currently None.
     """
     # handle none-locatable adapters (A)
     if not ILocation.providedBy(adapter):
@@ -42,18 +43,21 @@ def assertLocation(adapter, parent):
 
 
 class LocatingTrustedAdapterFactory(object):
-    """Adapt an adapter factory to provide trusted and (locatable) adapters.
+    """
+    Adapt an adapter factory to provide trusted and (locatable) adapters.
 
     Trusted adapters always adapt unproxied objects. If asked to
     adapt any proxied objects, it will unproxy them and then
     security-proxy the resulting adapter (S) unless the objects where not
     security-proxied before (N).
 
     Further locating trusted adapters provide a location for protected
-    adapters only (S). If such a protected adapter itself does not provide
-    ILocation it is wrapped within a location proxy and it parent will
-    be set. If the adapter does provide ILocation and it's __parent__ is None,
-    we set the __parent__ to the adapter's context:
+    adapters only (S). If such a protected adapter itself does not
+    provide ILocation it is wrapped within a location proxy and it
+    parent will be set. If the adapter does provide
+    :class:`zope.location.interfaces.ILocation` and its
+    ``__parent__`` is None, we set the ``__parent__`` to the adapter's
+    context.
     """
     def __init__(self, factory):
         self.factory = factory
@@ -83,15 +87,17 @@ def __call__(self, *args):
 
 
 class TrustedAdapterFactory(LocatingTrustedAdapterFactory):
-    """Adapt an adapter factory to provide trusted adapters.
+    """
+    Adapt an adapter factory to provide trusted adapters.
 
     Trusted adapters always adapt unproxied objects. If asked to
     adapt any proxied objects, it will unproxy them and then
     security-proxy the resulting adapter unless the objects where not
     security-proxied before.
 
-    If the adapter does provide ILocation and it's __parent__ is None,
-    we set the __parent__ to the adapter's context.
+    If the adapter does provide
+    :class:`zope.location.interfaces.ILocation` and its ``__parent__``
+    is None, we set the ``__parent__`` to the adapter's context.
     """
 
     # do not location-proxy the adapter
@@ -100,17 +106,20 @@ def _customizeProtected(self, adapter, context):
 
 
 class LocatingUntrustedAdapterFactory(object):
-    """Adapt an adapter factory to provide locatable untrusted adapters
+    """
+    Adapt an adapter factory to provide locatable untrusted adapters
 
     Untrusted adapters always adapt proxied objects. If any permission
-    other than zope.Public is required, untrusted adapters need a location
-    in order that the local authentication mechanism can be inovked
-    correctly.
-
-    If the adapter does not provide ILocation, we location proxy it and
-    set the parent. If the adapter does provide ILocation and
-    it's __parent__ is None, we set the __parent__ to the adapter's
-    context only:
+    other than :const:`zope.Public
+    <zope.security.interfaces.PUBLIC_PERMISSION_NAME>` is required,
+    untrusted adapters need a location in order that the local
+    authentication mechanism can be inovked correctly.
+
+    If the adapter does not provide
+    :class:`zope.location.interfaces.ILocation`, we location proxy it
+    and set the parent. If the adapter does provide ``ILocation`` and
+    its ``__parent__`` is None, we set the ``__parent__`` to the
+    adapter's context only.
     """
 
     def __init__(self, factory):