module sphinxext.sphinx_githublink_extension
¶
Short summary¶
module pyquickhelper.sphinxext.sphinx_githublink_extension
Defines a sphinx extension to display a link on github.
Classes¶
class |
truncated documentation |
---|---|
defines githublink node |
Functions¶
function |
truncated documentation |
---|---|
Defines custom role githublink. The following instruction add a link to the documentation on github. |
|
Create a link to a github file. |
|
setup for |
Properties¶
property |
truncated documentation |
---|---|
|
Return the document root node of the tree containing this Node. |
Documentation¶
Defines a sphinx extension to display a link on github.
- class pyquickhelper.sphinxext.sphinx_githublink_extension.githublink_node(rawsource='', *children, **attributes)[source]¶
Bases:
Element
defines githublink node
- pyquickhelper.sphinxext.sphinx_githublink_extension.githublink_role(role, rawtext, text, lineno, inliner, options=None, content=None)[source]¶
Defines custom role githublink. The following instruction add a link to the documentation on github.
- Parameters:
role – The role name used in the document.
rawtext – The entire markup snippet, with role.
text – The text marked with the role.
lineno – The line number where rawtext appears in the input.
inliner – The inliner instance that called us.
options – Directive options for customization (dictionary)
content – The directive content for customization (list)
- Returns:
[node], []
The pipe
|
indicates that an extension must be added to docname to get the true url.Different formats handled by the role:
anchor
: anchor = filename, line number is guess form the position in the fileanchor|py|*
: extension .py is added to the anchor, no line numberanchor|py|45
: extension .py is added to the anchor, line number is 45%|py|45
: the anchor name comes from the variablegithublink_options['anchor']
in the configuration file.
A suffix can be added to the extension
rst-doc
to tell the extension the source comes from the subfolder_doc/sphinx/source
and not from a subfolder likesrc
.
- pyquickhelper.sphinxext.sphinx_githublink_extension.make_link_node(rawtext, app, path, anchor, lineno, options, settings)[source]¶
Create a link to a github file.
- Parameters:
rawtext – Text being replaced with link node.
app – Sphinx application context
path – path to filename
lineno – line number
anchor – anchor
options – Options dictionary passed to role func.
settings – settings
The configuration of the documentation must contain a member
githublink_options
(a dictionary) which contains the following fields either the pair:user, project: to form the url
https://github.com/<user>/<project>
Or the field:
processor: function with takes a path and a line number and returns an url and an anchor name
Example:
def processor_github(path, lineno): url = "https://github.com/{0}/{1}/blob/master/{2}".format(user, project, path) if lineno: url += "#L{0}".format(lineno) return url, "source on GitHub"