sidebar_links

Directive which adds a toctree to the sidebar containing links to the GitHub repository, PyPI project page etc.

New in version 2.9.0.

Enable sphinx_toolbox.sidebar_links by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.sidebar_links',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

.. sidebar-links::

Adds a toctree to the sidebar containing links to the GitHub repository, PyPI project page etc. The toctree is only shown in the sidebar and is hidden with non-HTML builders.

You can see an example of this in the sidebar of this documentation.

Note

This directive can only be used on the root document (i.e. index.rst).

:github: (flag)

Flag to add a link to the project’s GitHub repository.

To use this option add the following to your conf.py:

extensions = [
        ...
        'sphinx_toolbox.github',
        ]

github_username = '<your username>'
github_repository = '<your repository>'

See sphinx_toolbox.github for more information.

:pypi: (string)

Flag to add a link to the project page on PyPI.

The name of the project on PyPI must be passed as the option’s value.

:caption: (string)

The caption of the toctree. Defaults to Links

Additional toctree entries may be added as the content of the directive, in the same manner as normal toctrees.

API Reference

Classes:

SidebarLinksDirective(name, arguments, ...)

Directive which adds a toctree to the sidebar containing links to the GitHub repository, PyPI project page etc.

Functions:

setup(app)

Setup sphinx_toolbox.sidebar_links.

class SidebarLinksDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SphinxDirective

Directive which adds a toctree to the sidebar containing links to the GitHub repository, PyPI project page etc.

Methods:

process_github_option()	Process the :github: flag.
run()	Create the installation node.

has_content = True

Type:    bool

option_spec = {'caption': <function unchanged_required>, 'github': <function flag>, 'pypi': <function unchanged_required>}

Type:    Mapping[str, Callable[[str], Any]]

process_github_option()

Process the :github: flag.

Return type:

str

run()

Create the installation node.

Return type:

List[Node]

setup(app)

Setup sphinx_toolbox.sidebar_links.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata