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

github_username
Type: str
Required: True

The username of the GitHub account that owns the repository this documentation corresponds to.

github_repository
Type: str
Required: True

The GitHub repository this documentation corresponds to.

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`

#1

You can also reference an issue in a different repository by adding the repository name inside <>.

:github:issue:`7680 <pytest-dev/pytest>`

pytest-dev/pytest#7680

: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`

#2

You can also reference a pull request in a different repository by adding the repository name inside <>.

:github:pull:`7671 <pytest-dev/pytest>`

pytest-dev/pytest#7671

:github:repo:

Role which shows a link to the given repository on GitHub.

Example

:github:repo:`sphinx-toolbox/sphinx-toolbox`

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`

@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`

@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:

GitHubDomain(env)

Sphinx domain for GitHub.com.

Functions:

validate_config(app, config)

Validate the provided configuration values.

setup(app)

Setup sphinx_toolbox.github.

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

SphinxExtMetadata

github.issues submodule

Roles and nodes for GitHub issues and Pull Requests.

Classes:

IssueNode(issue_number, refuri, **kwargs)

Docutils Node to represent a link to a GitHub Issue or Pull Request.

IssueNodeWithName(repo_name, issue_number, …)

Docutils Node to represent a link to a GitHub Issue or Pull Request, with the repository name shown.

Functions:

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

Adds a link to the given issue on GitHub.

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

Adds a link to the given pulll request on GitHub.

visit_issue_node(translator, node)

Visit an IssueNode.

depart_issue_node(translator, node)

Depart an IssueNode.

get_issue_title(issue_url)

Returns the title of the issue with the given url, or None if the issue isn’t found.

class IssueNode(issue_number, refuri, **kwargs)[source]

Bases: reference

Docutils Node to represent a link to a GitHub Issue or Pull Request.

Parameters
  • issue_number (Union[str, int]) – The number of the issue or pull request.

  • refuri (Union[str, URL]) – The URL of the issue / pull request on GitHub.

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.

Parameters
  • repo_name (str) – The full name of the repository, in the form owner/name.

  • issue_number (Union[str, int]) – The number of the issue or pull request.

  • refuri (Union[str, URL]) – The URL of the issue / pull request on GitHub.

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) – The docutils.parsers.rst.states.Inliner object that called issue_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 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[List[IssueNode], List[system_message]]

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) – The docutils.parsers.rst.states.Inliner object that called pull_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 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[List[IssueNode], List[system_message]]

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.

depart_issue_node(translator, node)[source]

Depart an IssueNode.

Parameters
  • translator (HTMLTranslator)

  • node (IssueNode) – The node being visited.

get_issue_title(issue_url)[source]

Returns the title of the issue with the given url, or None if the issue isn’t found.

Parameters

issue_url (str)

Return type

Optional[str]

github.repos_and_users submodule

Roles and nodes for referencing GitHub repositories and organizations.

Classes:

GitHubObjectLinkNode(name, refuri, **kwargs)

Docutils Node to represent a link to a GitHub repository.

Functions:

repository_role(name, rawtext, text, lineno, …)

Adds a link to the given repository on GitHub.

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

Adds a link to the given user / organization on GitHub.

visit_github_object_link_node(translator, node)

Visit a GitHubObjectLinkNode.

depart_github_object_link_node(translator, node)

Depart an GitHubObjectLinkNode.

class GitHubObjectLinkNode(name, refuri, **kwargs)[source]

Bases: reference

Docutils Node to represent a link to a GitHub repository.

Parameters
  • repo_name – The full name of the repository, in the form owner/name.

  • refuri (Union[str, URL]) – The URL of the issue / pull request on GitHub.

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) – The docutils.parsers.rst.states.Inliner object that called repository_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 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[List[reference], List[system_message]]

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) – The docutils.parsers.rst.states.Inliner object that called user_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 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[List[reference], List[system_message]]

Returns

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

Visit a GitHubObjectLinkNode.

Parameters

Depart an GitHubObjectLinkNode.

Parameters