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.

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 extensions and setup an epydoc_mapping:

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 re.match()) to be cross-referenced with the base url.

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

epydoc_mapping = {
   'http://paludis.exherbo.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`.

The group at the end of the pattern allows to reference the top-level 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:

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

Changelog

0.6 (Jun 28, 2012)

  • Migrate to Github
  • [#1] Continuous testing on Travis-CI

0.5 (Jan 7, 2012)

  • Python 3 support
  • Require Sphinx 1.1 now

0.4.1 (Aug 28, 2011)

  • Requires Sphinx 1.0 now
  • Fixed method cross-references

0.4 (May 21, 2010)

  • Initial release

License

Copyright (c) 2010, 2011, 2012 Sebastian Wiesner <lunaryorn@googlemail.com>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.