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, 7 insertions, 2 deletions

diff --git a/src/zope/component/globalregistry.py b/src/zope/component/globalregistry.py
index 80b0d72..d48d39b 100644
--- a/src/zope/component/globalregistry.py
+++ b/src/zope/component/globalregistry.py
@@ -13,11 +13,11 @@
 ##############################################################################
 """Global components support
 """
-from zope.interface import implementer
 from zope.interface.adapter import AdapterRegistry
 from zope.interface.registry import Components
 
-from zope.interface.interfaces import IComponentLookup
+from zope.component.interfaces import inherits_arch_docs
+from zope.component.interfaces import inherits_reg_docs
 
 
 def GAR(components, registryName):
@@ -59,6 +59,7 @@ else:
     del addCleanUp
 
 globalSiteManager = base
+@inherits_arch_docs
 def getGlobalSiteManager():
     return globalSiteManager
 
@@ -66,14 +67,18 @@ def getGlobalSiteManager():
 # We eventually want to deprecate these in favor of using the global
 # component registry directly.
 
+@inherits_reg_docs
 def provideUtility(component, provides=None, name=u''):
     base.registerUtility(component, provides, name, event=False)
 
+@inherits_reg_docs
 def provideAdapter(factory, adapts=None, provides=None, name=u''):
     base.registerAdapter(factory, adapts, provides, name, event=False)
 
+@inherits_reg_docs
 def provideSubscriptionAdapter(factory, adapts=None, provides=None):
     base.registerSubscriptionAdapter(factory, adapts, provides, event=False)
 
+@inherits_reg_docs
 def provideHandler(factory, adapts=None):
     base.registerHandler(factory, adapts, event=False)