Merge pull request #49 from zopefoundation/doc-module

Reference documentation improvements

docs/api.rst

@@ -1,10 +1,12 @@
-:mod:`zope.component` API Reference
-===================================
+=====================================
+ ``zope.component`` API Reference
+=====================================
 
 
 .. toctree::
    :maxdepth: 2
 
+   api/module
    api/interfaces
    api/sitemanager
    api/utility
@@ -13,3 +15,4 @@
    api/interface
    api/security
    api/persistent
+   api/hooks

docs/api/adapter.rst

@@ -1,15 +1,24 @@
-Adapter Registration APIs
-=========================
+===========================
+ Adapter Registration APIs
+===========================
+
+This document covers a specific subset of the APIs in :mod:`zope.component`.
+
+.. currentmodule:: zope.component
 
 .. testsetup::
 
    from zope.component.testing import setUp
    setUp()
 
-.. autofunction:: zope.component.provideUtility
+.. autofunction:: zope.component.provideAdapter
+
+.. autofunction:: zope.component.provideHandler
+
+.. autofunction:: zope.component.provideSubscriptionAdapter
 
 Conforming Adapter Lookup
--------------------------
+=========================
 
 .. autofunction:: zope.component.getAdapterInContext
 
@@ -21,7 +30,7 @@ context object to see if it already conforms to the requested interface.
 If so, the object is returned immediately.  Otherwise, the adapter factory
 is looked up in the site manager, and called.
 
-Let's start by creating a component that supports the `__conform__()` method:
+Let's start by creating a component that supports the ``__conform__()`` method:
 
 .. doctest::
 
@@ -39,14 +48,14 @@ We also gave the component a custom representation, so it will be easier
 to use in these tests.
 
 We now have to create a site manager (other than the default global one)
-with which we can register adapters for `I1`.
+with which we can register adapters for ``I1``.
 
 .. doctest::
 
    >>> from zope.component.globalregistry import BaseGlobalComponents
    >>> sitemanager = BaseGlobalComponents()
 
-Now we create a new `context` that knows how to get to our custom site
+Now we create a new ``context`` that knows how to get to our custom site
 manager.
 
 .. doctest::
@@ -111,7 +120,7 @@ registered adapter:
    43
 
 Named Adapter Lookup
---------------------
+====================
 
 .. autofunction:: zope.component.getAdapter
 
@@ -141,7 +150,7 @@ returns the default:
    >>> queryAdapter(ob, I2, '', '<default>')
    '<default>'
 
-The 'requires' argument to `registerAdapter` must be a sequence, rather than
+The 'requires' argument to ``registerAdapter`` must be a sequence, rather than
 a single interface:
 
 .. doctest::
@@ -154,7 +163,7 @@ a single interface:
      ...
    TypeError: the required argument should be a list of interfaces, not a single interface
 
-After register an adapter from `I1` to `I2` with the global site manager:
+After register an adapter from ``I1`` to ``I2`` with the global site manager:
 
 .. doctest::
 
@@ -208,10 +217,10 @@ After registering under that name:
    True
 
 Invoking an Interface to Perform Adapter Lookup
------------------------------------------------
+===============================================
 
 :mod:`zope.component` registers an adapter hook with
-:mod:`zope.interface.interface`, allowing a convenient spelling for
+`zope.interface.interface.adapter_hooks`, allowing a convenient spelling for
 adapter lookup:  just "call" the interface, passing the context:
 
 .. doctest::
@@ -241,10 +250,10 @@ unless we pass a default:
    True
 
 Registering Adapters For Arbitrary Objects
-------------------------------------------
+==========================================
 
 Providing an adapter for None says that your adapter can adapt anything
-to `I2`.
+to ``I2``.
 
 .. doctest::
 
@@ -267,7 +276,7 @@ It can really adapt any arbitrary object:
    True
 
 Looking Up Adapters Using Multiple Objects
-------------------------------------------
+==========================================
 
 .. autofunction:: zope.component.getMultiAdapter
 
@@ -284,7 +293,7 @@ adapted:
 
 As with regular adapters, if an adapter isn't registered for the given
 objects and interface, the :func:`~zope.component.getMultiAdapter` API
-raises `ComponentLookupError`:
+raises `zope.interface.interfaces.ComponentLookupError`:
 
 .. doctest::
 
@@ -342,7 +351,7 @@ Now we can get the adapter:
 
 
 Finding More Than One Adapter
------------------------------
+=============================
 
 .. autofunction:: zope.component.getAdapters
 
@@ -388,17 +397,17 @@ factory returns None, it is as if it wasn't present.
 
 
 Subscription Adapters
----------------------
+=====================
 
 .. autofunction:: zope.component.subscribers
 
 Event handlers
---------------
+==============
 
 .. autofunction:: zope.component.handle
 
 Helpers for Declaring / Testing Adapters
-----------------------------------------
+========================================
 
 .. autofunction:: zope.component.adapter
 

docs/api/hooks.rst

@@ -0,0 +1,8 @@
+==========================================================
+ ``zope.component.hooks``: The current component registry
+==========================================================
+
+.. seealso:: :doc:`../hooks` for narrative documentation and examples.
+
+.. automodule:: zope.component.hooks
+   :noindex:

docs/api/module.rst

@@ -0,0 +1,12 @@
+============================================
+ ``zope.component``: Module-level functions
+============================================
+
+This document provides a summary of the APIs available directly from
+``zope.component``. For more details, see the remaining documentation.
+
+.. These are generally explored in more detail in
+   specific documentation, so default indexing should go
+   to that instead of here.
+.. automodule:: zope.component
+   :noindex:

docs/api/utility.rst

@@ -1,5 +1,8 @@
-Utility Registration APIs
-=========================
+===========================
+ Utility Registration APIs
+===========================
+
+.. autofunction:: zope.component.provideUtility
 
 .. autofunction:: zope.component.getUtility
 
@@ -56,7 +59,7 @@ Now the component is available:
 
 
 Named Utilities
----------------
+===============
 
 Registering a utility without a name does not mean that it is available
 when looking for the utility with a name:
@@ -84,7 +87,7 @@ Registering the utility under the correct name makes it available:
    True
 
 Querying Multiple Utilities
----------------------------
+===========================
 
 .. autofunction:: zope.component.getUtilitiesFor
 
@@ -159,7 +162,7 @@ the utilities.
 
 
 Delegated Utility Lookup
-------------------------
+========================
 
 .. autofunction:: zope.component.getNextUtility
 

docs/hooks.rst

@@ -74,6 +74,39 @@ If we set another site, that one will be considered current:
    >>> getSiteManager() is site2.registry
    True
 
+However, the default `zope.component.getSiteManager` function isn't
+yet aware of this:
+
+.. doctest::
+
+   >>> from zope.component import getSiteManager as global_getSiteManager
+   >>> global_getSiteManager()
+   <BaseGlobalComponents base>
+
+To integrate that with the notion of the current site, we need to call ``setHooks``:
+
+.. autofunction:: setHooks
+
+.. doctest::
+
+   >>> from zope.component.hooks import setHooks
+   >>> setHooks()
+   >>> getSiteManager() is site2.registry
+   True
+   >>> global_getSiteManager() is site2.registry
+   True
+
+This can be reversed using ``resetHooks``:
+
+.. autofunction:: resetHooks
+
+.. doctest::
+
+   >>> from zope.component.hooks import resetHooks
+   >>> resetHooks()
+   >>> global_getSiteManager()
+   <BaseGlobalComponents base>
+
 Finally we can unset the site and the global component registry is used again:
 
 .. doctest::

docs/testlayer.rst

@@ -4,6 +4,8 @@
 
 .. currentmodule:: zope.component.testlayer
 
+.. module:: zope.component.testlayer
+
 ``zope.component.testlayer`` defines two things:
 
 * a `LayerBase` that makes it easier and saner to use zope.testing's

src/zope/component/__init__.py

@@ -11,7 +11,16 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Zope 3 Component Architecture
+"""
+Zope 3 Component Architecture
+
+This module provides an implementation of
+:class:`~zope.component.interfaces.IComponentArchitecture`, using the
+current :mod:`site <zope.component.hooks>`.
+
+This module also provides an implementation of
+:class:`~zope.component.interfaces.IComponentRegistrationConvenience`
+using the `global site manager <getGlobalSiteManager>`_.
 """
 from zope.interface import Interface
 from zope.interface import implementedBy
@@ -58,4 +67,9 @@
 from zope.component._declaration import adapts
 
 moduleProvides(IComponentArchitecture, IComponentRegistrationConvenience)
-__all__ = tuple(IComponentArchitecture)
+__all__ = tuple(IComponentArchitecture) + tuple(IComponentRegistrationConvenience) + (
+    'named',
+    'adapts',
+    'adapter',
+    'adaptedBy',
+)