source

Add hyperlinks to source files, either on GitHub or in the documentation itself.

Enable sphinx_toolbox.source by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.source',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

If you’re looking for a [source] button to go at the end of your class and function signatures, checkout sphinx.ext.linkcode and sphinx.ext.viewcode.

Changed in version 4.0.0: The sphinx_toolbox.source module no longer enables the sphinx_toolbox.github extension automatically. If you have source_link_target set to 'GitHub' you may need to enable the extension manually.

Usage

Type: str
Required: False
Default: 'Sphinx'

The target of the source link, either 'GitHub' or 'Sphinx'. Case insensitive.

Note

The 'GitHub' source option requires the sphinx_toolbox.github extension to be enabled in your conf.py file, and its github_username and github_repository options set. See that extension’s documentation for more details.

:source:

Role which shows a link to the given source file, either on GitHub or within the Sphinx documentation.

By default, the link points to the code within the documentation, but can be configured to point to GitHub by setting source_link_target to 'GitHub'.

Example

:source:`sphinx_toolbox/config.py`

Here is the :source:`source code <sphinx_toolbox/config.py>`

sphinx_toolbox/config.py

Here is the source code

API Reference

Functions:

source_role(name, rawtext, text, lineno, inliner)

Adds a link to the given Python source file in the documentation or on GitHub.

setup(app)

Setup sphinx_toolbox.source.
source_role(name, rawtext, text, lineno, inliner, options={}, content=[])[source]

Adds a link to the given Python source file in the documentation or on GitHub.

Parameters:

  • name (str) – The local name of the interpreted role, the role name actually used in the document.

  • rawtext (str) – A string containing the entire interpreted text input, including the role and markup.

  • text (str) – The interpreted text content.

  • lineno (int) – The line number where the interpreted text begins.

  • inliner (Inliner) – The docutils.parsers.rst.states.Inliner object that called source_role(). It contains the several attributes useful for error reporting and document tree access.

  • options (Dict) – A dictionary of directive options for customization (from the role directive), to be interpreted by the function. Used for additional attributes for the generated elements and other functionality. Default {}.

  • content (List[str]) – A list of strings, the directive content for customization (from the role directive). To be interpreted by the function. Default [].

Return type:

Tuple[Sequence[Node], List[system_message]]

Returns:

A list containing the created node, and a list containing any messages generated during the function.

Changed in version 2.8.0: Now returns a sequence of nodes.reference and addnodes.pending_xref as the first tuple element, rather than nodes.reference and addnodes.pending_xref as in previous versions.

setup(app)[source]

Setup sphinx_toolbox.source.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata