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
.
Usage¶
-
source_link_target
¶ -
The target of the source link, either
'GitHub'
or'Sphinx'
. Case insensitive.
-
: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>`
Here is the source code
API Reference¶
Functions:
|
Adds a link to the given Python source file in the documentation or on GitHub. |
|
Setup |
-
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
) – Thedocutils.parsers.rst.states.Inliner
object that calledsource_role()
. It contains the several attributes useful for error reporting and document tree access.options (
Dict
) – A dictionary of directive options for customization (from therole
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 therole
directive). To be interpreted by the function. Default[]
.
- Return type
- 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
andaddnodes.pending_xref
as the first tuple element, rather thannodes.reference
andaddnodes.pending_xref
as in previous versions.
-
setup
(app)[source]¶ Setup
sphinx_toolbox.source
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type