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

sphinxcontrib.epydoc – Epydoc crossreferences

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:

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.
Use a topic branch to easily amend a pull request later, if necessary.
Write good commit messages.
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 that relates to but one subject with a clear title and description in grammatically correct, complete sentences.

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.