beanbag_docutils.sphinx.ext.intersphinx_utils

Sphinx extension to enhance intersphinx support.

This fixes some reference issues with option (see https://github.com/sphinx-doc/sphinx/pull/3769 for the equivalent upstream fix).

It also introduces a .. default-intersphinx:: directive that allows for specifying one or more intersphinx set prefixes that should be tried if a reference could not be found. For example:

.. default-intersphinx:: myapp1.5 python

:ref:`some-reference`

This does affect the process by which missing references are located. If an unprefixed reference is used, it will only match if the prefix is in the list above, which differs from the default behavior of looking through all intersphinx mappings.

Setup

This extension must be added to exetnsions in conf.py after the sphinx.ext.intersphinx extension is added. For example:

extensions = [
    ...
    'sphinx.ext.intersphinx',
    'beanbag_docutils.sphinx.ext.intersphinx',
    ...
]

Functions

setup(app)

Set up the Sphinx extension.

Classes

DefaultIntersphinx(name, arguments, options, ...)

Specifies one or more default intersphinx sets to use.

class beanbag_docutils.sphinx.ext.intersphinx_utils.DefaultIntersphinx(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

Specifies one or more default intersphinx sets to use.

required_arguments = 1

Number of required directive arguments.

optional_arguments = 100

Number of optional arguments after the required arguments.

SPLIT_RE = re.compile(',\\s*')
run()

Run the directive.

Returns:

An empty list, always.

Return type:

list

beanbag_docutils.sphinx.ext.intersphinx_utils.setup(app)

Set up the Sphinx extension.

This listens for the events needed to handle missing references, and registers directives.

Parameters:

app (sphinx.application.Sphinx) – The Sphinx application building the docs.