Python Project sphinx-pytype-substitution

Introduction

sphinx-pytype-substitution generates restructuredtext substitutions for python cross references.

Once added to the extensions list of the Sphinx configuration file conf.py it adds short and handy substitutions for modules and classes.

So, on one side it becomes easy to add cross references to some api documentation in the project. And on the other side these references are still easy readable, even if the text is displayed directly (as it happens on GitHub.com or on PyPi.org).

Install

The latest stable version can always be installed or updated via pip:

$ pip install sphinx-pytype-substitution

Usage

Once available add the extension to then extensions list in config.py

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx_pytype_substitution',
    'sphinx_rtd_theme',
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon'
]

And add the modules or classes to reference to as

# -- Config for pytype_substitution extension ------------------------------

pytype_substitutions = pkg,  # package, module or class to reference to

Additional options let select specific references

pytype_match_pattern = ''  # regex to filter entities to ref to
pytype_exclude_pattern = ''  # regex to exclude entities to ref to

and decide if the substitution should have short or full format, i.e.

pytype_short_ref = True  # drop module from reference (if it does not conflict)

for |date()| rather than |datetime.date()|. Note, sometimes the defining module matters as for |open()| vs |gzip.open()|.

During initialisation process of Sphinx the list of substitutions is generated and added to rst_epilog.

So the substitutions are available for every page.

To see which substitutions are added add

pytype_show = True  # print out all pytype_substitutions

License

Code and documentation are available according to the license (see LICENSE file in repository).