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.