.. highlight:: rest

:mod:`lunar.sphinx.ext.epydoc` -- Epydoc crossreferences
========================================================

.. module:: lunar.sphinx.ext.epydoc
   :synopsis: Cross-reference epydoc documentation

This extension cross-references API documentation generated by epydoc_.
It works with the standard roles of the Python domain.

Use the following configuration value to activate the cross-referencing:

.. confval:: epydoc_mapping

   A dictionary mapping URIs to a list of regular expression.

   Each key of this dictionary is a base url of an epydoc-generated
   documentation.  Each value is a list of regular expressions, the
   reference target must match (see :func:`re.match`) to be cross-referenced
   with the base url.

   For instance, assume this value was set to the following:

   .. code-block:: python

      epydoc_mapping = {
         'http://paludis.pioto.org/api/python/': [r'paludis\.'],
         }

   Then the following cross-reference would link to the documentation of the
   `paludis.PackageID`_ class::

      This is a cross-reference to the :class:`paludis.PackageID`


.. _epydoc: http://epydoc.sourceforge.net/
.. _`paludis.PackageID`: http://paludis.pioto.org/api/python/paludis.PackageID-class.html