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

:anaconda: (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.

The branch name defaults to master, but a different branch name or a tag can be specified as follows:

.. installation: foo
    :github: dev

.. installation: bar
    :github: v1.2.3

Changed in version 3.10.0: Allow branch name to be specified.

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

First add the required channels

conda config --add channels https://conda.anaconda.org/domdfcoding
conda config --add channels https://conda.anaconda.org/conda-forge

Then install

conda install sphinx-toolbox

python3 -m pip install git+https://github.com/sphinx-toolbox/sphinx-toolbox@master --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.

has_content = True¶: Type: bool

option_spec = {'first': <function flag>, 'import-name': <function unchanged_required>, 'no-postamble': <function flag>, 'no-preamble': <function flag>}¶: Type: Mapping[str, Callable[[str], Any]]

optional_arguments = 1¶: Type: int

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.

has_content = True¶: Type: bool

option_spec = {'anaconda': <function flag>, 'conda-channels': <function unchanged>, 'conda-name': <function unchanged>, 'github': <function _validate_github_branch>, 'pypi': <function flag>, 'pypi-name': <function unchanged>}¶: Type: Mapping[str, Callable[[str], Any]]

optional_arguments = 1¶: Type: int

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:

options (Dict[str, Any]) – Mapping of option names to values.
env (BuildEnvironment) – The Sphinx build environment.

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:

options (Dict[str, Any]) – Mapping of option names to values.
env (BuildEnvironment) – The Sphinx build environment.

Return type:

List[str]

make_installation_instructions(options, env)[source]¶

Make the content of an installation node.

Parameters:

options (Dict[str, Any])
env (BuildEnvironment) – The Sphinx build environment.

Return type:

List[str]

pypi_installation(options, env)[source]¶

Source to provide instructions for installing from PyPI.

Parameters:

options (Dict[str, Any]) – Mapping of option names to values.
env (BuildEnvironment) – The Sphinx build environment.

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.

installation¶

Configuration¶

Usage¶

API Reference¶

`installation`¶