github
¶
Sphinx domain for GitHub.com, and related utilities.
New in version 2.4.0.
Enable sphinx_toolbox.github
by adding the following
to the extensions
variable in your conf.py
:
extensions = [
...
'sphinx_toolbox.github',
]
For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .
Configuration¶
Usage¶
-
:github:issue:
¶ Role which shows a link to the given issue on GitHub.
If the issue exists, the link has a tooltip that shows the title of the issue.
Example
:github:issue:`1`
You can also reference an issue in a different repository by adding the repository name inside
<>
.:github:issue:`7680 <pytest-dev/pytest>`
-
:github:pull:
¶ Role which shows a link to the given pull request on GitHub.
If the pull requests exists, the link has a tooltip that shows the title of the pull requests.
Example
:github:pull:`2`
You can also reference a pull request in a different repository by adding the repository name inside
<>
.:github:pull:`7671 <pytest-dev/pytest>`
-
:github:repo:
¶ Role which shows a link to the given repository on GitHub.
Example
:github:repo:`sphinx-toolbox/sphinx-toolbox`
You can also use a different label for the link:.
See more in the :github:repo:`pytest repository <pytest-dev/pytest>`.
See more in the pytest repository.
-
:github:user:
¶ Role which shows a link to the given user on GitHub.
Example
:github:user:`domdfcoding`
You can also use a different label for the link:.
See more of my :github:user:`repositories <domdfcoding>`.
See more of my repositories.
-
:github:org:
¶ Role which shows a link to the given organization on GitHub.
Example
:github:org:`sphinx-toolbox`
You can also use a different label for the link:.
See more repositories in the :github:org:`pytest-dev org <pytest-dev>`.
See more repositories in the pytest-dev org.
Caching¶
HTTP requests to obtain issue/pull request titles are cached for four hours.
To clear the cache manually, run:
python3 -m sphinx_toolbox
API Reference¶
Enable this extension from your extension’s setup function like so:
def setup(app: Sphinx) -> Dict[str, Any]:
app.setup_extension('sphinx_toolbox.github')
return {}
This will guarantee that the following values will be available via
app.config
:
github_username (
str
) – The username of the GitHub account that owns the repository this documentation corresponds to.github_repository (
str
) – The GitHub repository this documentation corresponds to.github_url (
apeye.requests_url.RequestsURL
) – The complete URL of the repository on GitHub.github_source_url (
RequestsURL
) – The base URL for the source code on GitHub.github_issues_url (
RequestsURL
) – The base URL for the issues on GitHub.github_pull_url (
RequestsURL
) – The base URL for the pull requests on GitHub.
If the user has not provided either github_username
or github_repository
a MissingOptionError
will be raised.
Classes:
|
Sphinx domain for GitHub.com. |
Functions:
|
Validate the provided configuration values. |
|
Setup |
-
class
GitHubDomain
(env)[source]¶ Bases:
Domain
Sphinx domain for GitHub.com.
-
validate_config
(app, config)[source]¶ Validate the provided configuration values.
See
ToolboxConfig
for a list of the configuration values.- Parameters
app (
Sphinx
) – The Sphinx application.config (
Config
)
-
setup
(app)[source]¶ Setup
sphinx_toolbox.github
.New in version 1.0.0.
- Parameters
app (
Sphinx
) – The Sphinx application.- Return type
github.issues
submodule¶
Roles and nodes for GitHub issues and Pull Requests.
Classes:
|
Docutils Node to represent a link to a GitHub Issue or Pull Request. |
|
Docutils Node to represent a link to a GitHub Issue or Pull Request, with the repository name shown. |
Functions:
|
Adds a link to the given issue on GitHub. |
|
Adds a link to the given pulll request on GitHub. |
|
Visit an |
|
Depart an |
|
Returns the title of the issue with the given url, or |
-
class
IssueNode
(issue_number, refuri, **kwargs)[source]¶ Bases:
reference
Docutils Node to represent a link to a GitHub Issue or Pull Request.
-
class
IssueNodeWithName
(repo_name, issue_number, refuri, **kwargs)[source]¶ Bases:
IssueNode
Docutils Node to represent a link to a GitHub Issue or Pull Request, with the repository name shown.
New in version 2.4.0.
-
issue_role
(name, rawtext, text, lineno, inliner, options={}, content=[])[source]¶ Adds a link to the given issue 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 calledissue_role()
. It contains the several attributes useful for error reporting and document tree access.options (
Dict
[str
,Any
]) – 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.
-
pull_role
(name, rawtext, text, lineno, inliner, options={}, content=[])[source]¶ Adds a link to the given pulll request 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 calledpull_role()
. It contains the several attributes useful for error reporting and document tree access.options (
Dict
[str
,Any
]) – 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.
-
visit_issue_node
(translator, node)[source]¶ Visit an
IssueNode
.If the node points to a valid issue / pull request, add a tooltip giving the title of the issue / pull request and a hyperlink to the page on GitHub.
- Parameters
translator (
HTMLTranslator
)node (
IssueNode
) – The node being visited.
github.repos_and_users
submodule¶
Roles and nodes for referencing GitHub repositories and organizations.
Classes:
|
Docutils Node to represent a link to a GitHub repository. |
Functions:
|
Adds a link to the given repository on GitHub. |
|
Adds a link to the given user / organization on GitHub. |
|
Visit a |
|
Depart an |
-
class
GitHubObjectLinkNode
(name, refuri, **kwargs)[source]¶ Bases:
reference
Docutils Node to represent a link to a GitHub repository.
-
repository_role
(name, rawtext, text, lineno, inliner, options={}, content=[])[source]¶ Adds a link to the given repository 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 calledrepository_role()
. It contains the several attributes useful for error reporting and document tree access.options (
Dict
[str
,Any
]) – 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.
-
user_role
(name, rawtext, text, lineno, inliner, options={}, content=[])[source]¶ Adds a link to the given user / organization 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 calleduser_role()
. It contains the several attributes useful for error reporting and document tree access.options (
Dict
[str
,Any
]) – 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.
-
visit_github_object_link_node
(translator, node)[source]¶ Visit a
GitHubObjectLinkNode
.- Parameters
translator (
HTMLTranslator
)node (
GitHubObjectLinkNode
) – The node being visited.
-
depart_github_object_link_node
(translator, node)[source]¶ Depart an
GitHubObjectLinkNode
.- Parameters
translator (
HTMLTranslator
)node (
GitHubObjectLinkNode
) – The node being visited.