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, 26 insertions, 1 deletions

diff --git a/src/zope/component/interfaces.py b/src/zope/component/interfaces.py
index f602476..15fbb55 100644
--- a/src/zope/component/interfaces.py
+++ b/src/zope/component/interfaces.py
@@ -11,7 +11,11 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ############################################################################
-"""Component and Component Architecture Interfaces
+"""
+Component and Component Architecture Interfaces
+
+The `IComponentArchitecture` and `IComponentRegistrationConvenience` interfaces
+are provided by `zope.component` directly.
 """
 from zope.interface import Attribute
 from zope.interface import Interface
@@ -380,3 +384,24 @@ class IFactory(Interface):
         created by this factory will implement. If the callable's Implements
         instance cannot be created, an empty Implements instance is returned.
         """
+
+
+# Internal helpers
+
+def _inherits_docs(func, iface):
+    doc = iface[func.__name__].__doc__
+    # By adding the ..seealso:: we get a link from our overview page
+    # to the specific narrative place where the function is described, because
+    # our overview page uses :noindex:
+    doc += "\n        .. seealso::"
+    doc += "\n           Function `~zope.component.%s` for notes, and " % (func.__name__,)
+    doc += "\n           `~zope.component.interfaces.%s` for the defining interface." % (iface.__name__,)
+    doc += "\n"
+    func.__doc__ = doc
+    return func
+
+def inherits_arch_docs(func):
+    return _inherits_docs(func, IComponentArchitecture)
+
+def inherits_reg_docs(func):
+    return _inherits_docs(func, IComponentRegistrationConvenience)