Reference documentation improvementsdoc-module

- Make it possible to use :mod:`zope.component`
- Provide a concise list of all the available APIs in that module and
  link them to their in-depth descriptions.
- Fix several xref errors
- Add documentation for setHooks/resetHooks.

This also makes it possible to get useful help at the REPL or command
line:

$ python -c 'import zope.component; help(zope.component.getAdapters)'
Help on function getAdapters in module zope.component._api:

getAdapters(objects, provided, context=None)
    Look for all matching adapters to a provided interface for
    objects

    Return a list of adapters that match. If an adapter is named,
    only the most specific adapter of a given name is returned.

    .. seealso::
       Function `~zope.component.getAdapters` for notes, and
       `~zope.component.interfaces.IComponentArchitecture` for the defining interface.

1 files changed, 33 insertions, 0 deletions

diff --git a/docs/hooks.rst b/docs/hooks.rst
index a2a77c7..382e69b 100644
--- a/docs/hooks.rst
+++ b/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::