added cross-referencing in docstrings, some formatting improvements

Signed-off-by: Oleg Höfling <[email protected]>

src/pluggy/hooks.py

@@ -11,8 +11,8 @@ class HookspecMarker(object):
     """ Decorator helper class for marking functions as hook specifications.
 
     You can instantiate it with a project_name to get a decorator.
-    Calling PluginManager.add_hookspecs later will discover all marked functions
-    if the PluginManager uses the same project_name.
+    Calling :py:meth:`.PluginManager.add_hookspecs` later will discover all marked functions
+    if the :py:class:`.PluginManager` uses the same project_name.
     """
 
     def __init__(self, project_name):
@@ -22,15 +22,15 @@ def __call__(
         self, function=None, firstresult=False, historic=False, warn_on_impl=None
     ):
         """ if passed a function, directly sets attributes on the function
-        which will make it discoverable to add_hookspecs().  If passed no
-        function, returns a decorator which can be applied to a function
+        which will make it discoverable to :py:meth:`.PluginManager.add_hookspecs`.
+        If passed no function, returns a decorator which can be applied to a function
         later using the attributes supplied.
 
-        If firstresult is True the 1:N hook call (N being the number of registered
+        If ``firstresult`` is ``True`` the 1:N hook call (N being the number of registered
         hook implementation functions) will stop at I<=N when the I'th function
-        returns a non-None result.
+        returns a non-``None`` result.
 
-        If historic is True calls to a hook will be memorized and replayed
+        If ``historic`` is ``True`` calls to a hook will be memorized and replayed
         on later registered plugins.
 
         """
@@ -58,9 +58,9 @@ def setattr_hookspec_opts(func):
 class HookimplMarker(object):
     """ Decorator helper class for marking functions as hook implementations.
 
-    You can instantiate with a project_name to get a decorator.
-    Calling PluginManager.register later will discover all marked functions
-    if the PluginManager uses the same project_name.
+    You can instantiate with a ``project_name`` to get a decorator.
+    Calling :py:meth:`.PluginManager.register` later will discover all marked functions
+    if the :py:class:`.PluginManager` uses the same project_name.
     """
 
     def __init__(self, project_name):
@@ -76,25 +76,25 @@ def __call__(
     ):
 
         """ if passed a function, directly sets attributes on the function
-        which will make it discoverable to register().  If passed no function,
-        returns a decorator which can be applied to a function later using
-        the attributes supplied.
+        which will make it discoverable to :py:meth:`.PluginManager.register`.
+        If passed no function, returns a decorator which can be applied to a
+        function later using the attributes supplied.
 
-        If optionalhook is True a missing matching hook specification will not result
+        If ``optionalhook`` is ``True`` a missing matching hook specification will not result
         in an error (by default it is an error if no matching spec is found).
 
-        If tryfirst is True this hook implementation will run as early as possible
+        If ``tryfirst`` is ``True`` this hook implementation will run as early as possible
         in the chain of N hook implementations for a specification.
 
-        If trylast is True this hook implementation will run as late as possible
+        If ``trylast`` is ``True`` this hook implementation will run as late as possible
         in the chain of N hook implementations.
 
-        If hookwrapper is True the hook implementations needs to execute exactly
-        one "yield".  The code before the yield is run early before any non-hookwrapper
-        function is run.  The code after the yield is run after all non-hookwrapper
-        function have run.  The yield receives a ``_Result`` object representing
-        the exception or result outcome of the inner calls (including other hookwrapper
-        calls).
+        If ``hookwrapper`` is ``True`` the hook implementations needs to execute exactly
+        one ``yield``.  The code before the ``yield`` is run early before any non-hookwrapper
+        function is run.  The code after the ``yield`` is run after all non-hookwrapper
+        function have run.  The ``yield`` receives a :py:class:`.callers._Result` object
+        representing the exception or result outcome of the inner calls (including other
+        hookwrapper calls).
 
         """
 
@@ -290,7 +290,7 @@ def call_historic(self, result_callback=None, kwargs=None, proc=None):
         for all plugins which will be registered afterwards.
 
         If ``result_callback`` is not ``None`` it will be called for for each
-        non-None result obtained from a hook implementation.
+        non-``None`` result obtained from a hook implementation.
 
         .. note::
             The ``proc`` argument is now deprecated.
@@ -314,7 +314,7 @@ def call_historic(self, result_callback=None, kwargs=None, proc=None):
 
     def call_extra(self, methods, kwargs):
         """ Call the hook with some additional temporarily participating
-        methods using the specified kwargs as call parameters. """
+        methods using the specified ``kwargs`` as call parameters. """
         old = list(self._nonwrappers), list(self._wrappers)
         for method in methods:
             opts = dict(hookwrapper=False, trylast=False, tryfirst=False)

src/pluggy/manager.py

@@ -50,22 +50,23 @@ def __dir__(self):
 
 
 class PluginManager(object):
-    """ Core Pluginmanager class which manages registration
+    """ Core :py:class:`.Pluginmanager` class which manages registration
     of plugin objects and 1:N hook calling.
 
-    You can register new hooks by calling ``add_hookspecs(module_or_class)``.
+    You can register new hooks by calling :py:meth:`add_hookspecs(module_or_class)
+    <.PluginManager.add_hookspecs>`.
     You can register plugin objects (which contain hooks) by calling
-    ``register(plugin)``.  The Pluginmanager is initialized with a
-    prefix that is searched for in the names of the dict of registered
-    plugin objects.
+    :py:meth:`register(plugin) <.PluginManager.register>`.  The :py:class:`.Pluginmanager`
+    is initialized with a prefix that is searched for in the names of the dict
+    of registered plugin objects.
 
-    For debugging purposes you can call ``enable_tracing()``
+    For debugging purposes you can call :py:meth:`.PluginManager.enable_tracing`
     which will subsequently send debug information to the trace helper.
     """
 
     def __init__(self, project_name, implprefix=None):
         """If ``implprefix`` is given implementation functions
-        will be recognized if their name matches the implprefix. """
+        will be recognized if their name matches the ``implprefix``. """
         self.project_name = project_name
         self._name2plugin = {}
         self._plugin2hookcallers = {}
@@ -92,9 +93,9 @@ def _hookexec(self, hook, methods, kwargs):
         return self._inner_hookexec(hook, methods, kwargs)
 
     def register(self, plugin, name=None):
-        """ Register a plugin and return its canonical name or None if the name
-        is blocked from registering.  Raise a ValueError if the plugin is already
-        registered. """
+        """ Register a plugin and return its canonical name or ``None`` if the name
+        is blocked from registering.  Raise a :py:class:`ValueError` if the plugin
+        is already registered. """
         plugin_name = name or self.get_canonical_name(plugin)
 
         if plugin_name in self._name2plugin or plugin in self._plugin2hookcallers:
@@ -176,11 +177,11 @@ def set_blocked(self, name):
         self._name2plugin[name] = None
 
     def is_blocked(self, name):
-        """ return True if the given plugin name is blocked. """
+        """ return ``True`` if the given plugin name is blocked. """
         return name in self._name2plugin and self._name2plugin[name] is None
 
     def add_hookspecs(self, module_or_class):
-        """ add new hook specifications defined in the given module_or_class.
+        """ add new hook specifications defined in the given ``module_or_class``.
         Functions are recognized if they have been decorated accordingly. """
         names = []
         for name in dir(module_or_class):
@@ -211,26 +212,27 @@ def get_plugins(self):
         return set(self._plugin2hookcallers)
 
     def is_registered(self, plugin):
-        """ Return True if the plugin is already registered. """
+        """ Return ``True`` if the plugin is already registered. """
         return plugin in self._plugin2hookcallers
 
     def get_canonical_name(self, plugin):
         """ Return canonical name for a plugin object. Note that a plugin
         may be registered under a different name which was specified
-        by the caller of register(plugin, name). To obtain the name
-        of an registered plugin use ``get_name(plugin)`` instead."""
+        by the caller of :py:meth:`register(plugin, name) <.PluginManager.register>`.
+        To obtain the name of an registered plugin use :py:meth:`get_name(plugin)
+        <.PluginManager.get_name>` instead."""
         return getattr(plugin, "__name__", None) or str(id(plugin))
 
     def get_plugin(self, name):
-        """ Return a plugin or None for the given name. """
+        """ Return a plugin or ``None`` for the given name. """
         return self._name2plugin.get(name)
 
     def has_plugin(self, name):
-        """ Return True if a plugin with the given name is registered. """
+        """ Return ``True`` if a plugin with the given name is registered. """
         return self.get_plugin(name) is not None
 
     def get_name(self, plugin):
-        """ Return name for registered plugin or None if not registered. """
+        """ Return name for registered plugin or ``None`` if not registered. """
         for name, val in self._name2plugin.items():
             if plugin == val:
                 return name
@@ -262,7 +264,7 @@ def _verify_hook(self, hook, hookimpl):
 
     def check_pending(self):
         """ Verify that all hooks which have not been verified against
-        a hook specification are optional, otherwise raise PluginValidationError"""
+        a hook specification are optional, otherwise raise :py:class:`.PluginValidationError`."""
         for name in self.hook.__dict__:
             if name[0] != "_":
                 hook = getattr(self.hook, name)
@@ -323,7 +325,7 @@ def add_hookcall_monitoring(self, before, after):
         of HookImpl instances and the keyword arguments for the hook call.
 
         ``after(outcome, hook_name, hook_impls, kwargs)`` receives the
-        same arguments as ``before`` but also a :py:class:`_Result`` object
+        same arguments as ``before`` but also a :py:class:`pluggy.callers._Result` object
         which represents the result of the overall hook call.
         """
         oldcall = self._inner_hookexec
@@ -357,7 +359,7 @@ def after(outcome, hook_name, methods, kwargs):
         return self.add_hookcall_monitoring(before, after)
 
     def subset_hook_caller(self, name, remove_plugins):
-        """ Return a new _HookCaller instance for the named method
+        """ Return a new :py:class:`.hooks._HookCaller` instance for the named method
         which manages calls to all registered plugins except the
         ones from remove_plugins. """
         orig = getattr(self.hook, name)