.. highlight:: rest

sphinxcontrib.epydoc -- Epydoc crossreferences
==============================================

A Sphinx_ extension to reference identifiers in API documentation generated by
Epydoc_.

The extension is available under the terms of the BSD license, see the
license_ for more information.

.. contents:: Contents


Installation
------------

Use ``pip`` to install this extension from the `Python Package Index`_::

   pip install sphinx-contrib.epydoc

This extension requires Sphinx 1.0 and Python 2.6 or Python 3.1.


Configuration
-------------

Add ``sphinxcontrib.epydoc`` to the configuration value
:confval:`extensions` and setup an :confval:`epydoc_mapping`:

.. 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.exherbo.org/api/python/': [r'paludis(\.|$)'],
   }

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

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

The group at the end of the pattern allows to reference the top-level
:mod:`paludis`, too.


Support
-------

Please report issues to the `issue tracker`_ if you have trouble, found a bug in
this extension or lack support for a specific issue tracker, but respect the
following rules:

- Check that the issue has not already been reported.
- Check that the issue is not already fixed in the ``master`` branch.
- Open issues with clear title and a detailed description in grammatically
  correct, complete sentences.


Development
-----------

The source code is hosted on Github_:

   git clone https://github.com/lunaryorn/sphinxcontrib-epydoc

Please fork the repository and send pull requests with your fixes or cool new
features, but respect the following rules:

- Read `how to properly contribute to open source projects on GitHub
  <http://gun.io/blog/how-to-github-fork-branch-and-pull-request/>`_.
- Use a topic branch to easily amend a pull request later, if necessary.
- Write `good commit messages
  <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
- Squash commits on the topic branch before opening a pull request.
- Respect :pep:`8` (use `pep8`_ to check your coding style compliance)
- Add unit tests.
- Open a `pull request <https://help.github.com/articles/using-pull-requests>`_
  that relates to but one subject with a clear title and description in
  grammatically correct, complete sentences.


Changelog
---------

.. include:: ../CHANGES.rst


.. _license:

License
-------

.. literalinclude:: ../LICENSE


.. _Sphinx: http://sphinx.pocoo.org/
.. _epydoc: http://epydoc.sourceforge.net/
.. _issue tracker: https://github.com/lunaryorn/sphinxcontrib-epydoc/issues
.. _python package index: http://pypi.python.org/pypi/sphinxcontrib-epydoc
.. _github: https://github.com/lunaryorn/sphinxcontrib-epydoc
.. _pep8: http://pypi.python.org/pypi/pep8/
