installation

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

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

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

Configuration

conda_channels
Type: List[str]
Required: False
Default: []

The conda channels required to install the library from Anaconda.

An alternative to setting it within the installation directive.

Usage

.. installation:: name

Adds a series of tabs providing installation instructions for the project from a number of sources.

The directive takes a single required argument – the name of the project. If the project uses a different name on PyPI and/or Anaconda, the :pypi-name: and :conda-name: options can be used to set the name for those repositories.

:pypi: (flag)

Flag to indicate the project can be installed from PyPI.

:pypi-name: name (string)

The name of the project on PyPI.

:conda: (flag)

Flag to indicate the project can be installed with Conda.

:conda-name: name (string)

The name of the project on Conda.

:conda-channels: channels (comma separated strings)

Comma-separated list of required Conda channels.

This can also be set via the conda_channels option.

:github: (flag)

Flag to indicate the project can be installed from GitHub.

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.

Example

.. installation:: sphinx-toolbox
    :pypi:
    :anaconda:
    :conda-channels: domdfcoding,conda-forge
    :github:

python3 -m pip install sphinx-toolbox --user

.. extensions::

Shows instructions on how to enable a Sphinx extension.

The directive takes a single argument – the name of the extension.

:import-name: (string)

The name used to import the extension, if different from the name of the extension.

:no-preamble: (flag)

Disables the preamble text.

:no-postamble: (flag)

Disables the postamble text.

:first: (flag)

Puts the entry for extension before its dependencies. By default is is placed at the end.

New in version 0.4.0.

Example

.. extensions:: sphinx-toolbox
    :import-name: sphinx_toolbox

    sphinx.ext.viewcode
    sphinx_tabs.tabs
    sphinx-prompt

Enable sphinx-toolbox by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx.ext.viewcode',
    'sphinx_tabs.tabs',
    'sphinx-prompt',
    'sphinx_toolbox',
    ]

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

API Reference

Classes:

ExtensionsDirective(name, arguments, …)

Directive to show instructions for enabling the extension.

InstallationDirective(name, arguments, …)

Directive to show installation instructions.

Sources(*args, **kwargs)

Class to store functions that provide installation instructions for different sources.

Functions:

conda_installation(options, env)

Source to provide instructions for installing from Anaconda.

copy_asset_files(app[, exception])

Copy additional stylesheets into the HTML build directory.

github_installation(options, env)

Source to provide instructions for installing from GitHub.

make_installation_instructions(options, env)

Make the content of an installation node.

pypi_installation(options, env)

Source to provide instructions for installing from PyPI.

setup(app)

Setup sphinx_toolbox.installation.

Data:

sources

Instance of Sources.

class ExtensionsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: SphinxDirective

Directive to show instructions for enabling the extension.

Methods:

run()

Create the extensions node.

run()[source]

Create the extensions node.

Return type

List[Node]

class InstallationDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: SphinxDirective

Directive to show installation instructions.

Attributes:

options

Mapping of option names to values.

Methods:

run()

Create the installation node.

run_generic()

Generate generic reStructuredText output.

run_html()

Generate output for HTML builders.

options

Type:    Dict[str, Any]

Mapping of option names to values.

The options are as follows:

  • pypi: Flag to indicate the project can be installed from PyPI.

  • pypi-name: The name of the project on PyPI.

  • conda: Flag to indicate the project can be installed with Conda.

  • conda-name: The name of the project on Conda.

  • conda-channels: Comma-separated list of required Conda channels.

  • github: Flag to indicate the project can be installed from GitHub.

The GitHub username and repository are configured in conf.py and are available in env.config.

run()[source]

Create the installation node.

Return type

List[Node]

run_generic()[source]

Generate generic reStructuredText output.

Return type

List[Node]

run_html()[source]

Generate output for HTML builders.

Return type

List[Node]

class Sources(*args, **kwargs)[source]

Bases: List[Tuple[str, str, Callable, Callable, Optional[Dict[str, Callable]]]]

Class to store functions that provide installation instructions for different sources.

The syntax of each entry is:

(option_name, source_name, getter_function, validator_function, extra_options)
  • option_name – a string to use in the directive to specify the source to use,

  • source_name – a string to use in the tabs to indicate the installation source,

  • getter_function – the function that returns the installation instructions,

  • validator_function – a function to validate the option value provided by the user,

  • extra_options – a mapping of additional options for the directive that are used by the getter_function.

register(option_name, source_name, validator=<function 'unchanged'>, extra_options=None)[source]

Decorator to register a function.

The function must have the following signature:

def function(
    options: Dict[str, Any],  # Mapping of option names to values.
    env: sphinx.environment.BuildEnvironment,  # The Sphinx build environment.
    ) -> List[str]: ...
Parameters
  • option_name (str) – A string to use in the directive to specify the source to use.

  • source_name (str) – A string to use in tabbed installation instructions to represent this source.

  • validator (Callable) – A function to validate the option value provided by the user. Default docutils.parsers.rst.directives.unchanged().

  • extra_options (Optional[Dict[str, Callable]]) – An optional mapping of extra option names to validator functions. Default {}.

Return type

Callable

Returns

The registered function.

Raises

SyntaxError if the decorated function does not take the correct arguments.

conda_installation(options, env)[source]

Source to provide instructions for installing from Anaconda.

Parameters
Return type

List[str]

copy_asset_files(app, exception=None)[source]

Copy additional stylesheets into the HTML build directory.

New in version 1.2.0.

Parameters
  • app (Sphinx) – The Sphinx application.

  • exception (Optional[Exception]) – Any exception which occurred and caused Sphinx to abort. Default None.

github_installation(options, env)[source]

Source to provide instructions for installing from GitHub.

Parameters
Return type

List[str]

make_installation_instructions(options, env)[source]

Make the content of an installation node.

Parameters
Return type

List[str]

pypi_installation(options, env)[source]

Source to provide instructions for installing from PyPI.

Parameters
Return type

List[str]

setup(app)[source]

Setup sphinx_toolbox.installation.

New in version 0.7.0.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata

sources

Type:    Sources

Instance of Sources.