shields

Directives for shield/badge images.

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

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

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

Usage

Several shield/badge directives are available.

They function similarly to the .. image:: directives, although not all options are available. As with the image directive, shields can be used as part of substitutions, e.g.

This repository uses pre-commit |pre-commit|

.. |pre-commit| pre-commit::

All shields have the following options:

:alt:

Alternative text for the shield, used when the image cannot be displayed or the user uses a screen reader.

:height:

:width:

:scale:

The height/width/scale of the shield.

:name:

:class: (string)

Additional CSS class for the shield. All shields have the sphinx_toolbox_shield class by default.

Shields

.. rtfd-shield::

Shield to show the ReadTheDocs documentation build status.

:project:

The name of the project on ReadTheDocs.

:version:

The documentation version. Default latest.

:target:

The hyperlink target of the shield. Useful if the documentation uses a custom domain.

New in version 1.8.0.

Examples

.. rtfd-shield::
    :project: sphinx-toolbox

.. rtfd-shield::
    :project: attrs
    :target: https://www.attrs.org/

.. pypi-shield::

Shield to show information about the project on PyPI.

:project:

The name of the project on PyPI.

Only one of the following options is permitted:

:version:

Show the package version.

:py-versions:

Show the supported python versions.

:implementations:

Show the supported python implementations.

:wheel:

Show whether the package has a wheel.

:license:

Show the license listed on PyPI.

:downloads:

Show the downloads for the given period (day / week / month)

Changed in version 2.5.0: Shields created with this option now link to pypistats.

Examples

.. pypi-shield::
    :version:

\

.. pypi-shield::
    :project: sphinx
    :downloads: month

.. maintained-shield::

Shield to indicate whether the project is maintained.

Takes a single argument: the current year.

Example

.. maintained-shield:: 2020

.. github-shield::

Shield to show information about a GitHub repository.

:username:

The GitHub username. Defaults to github_username.

:repository:

The GitHub repository. Defaults to github_repository.

:branch:

The branch to show information about. Default master.

Required for commits-since and last-commit.

Only one of the following options is permitted:

:contributors: (flag)

Show the number of contributors.

:commits-since: tag (string)

Show the number of commits since the given tag.

:last-commit: (flag)

Show the date of the last commit.

:top-language: (flag)

Show the top language and percentage.

:license: (flag)

Show the license detected by GitHub.

Examples

.. github-shield::
    :last-commit:

\

.. github-shield::
    :commits-since: v0.1.0

.. actions-shield::

Shield to show the GitHub Actions build status.

:username:

The GitHub username. Defaults to github_username.

:repository:

The GitHub repository. Defaults to github_repository.

:workflow:

The workflow to show the status for.

Example

.. actions-shield::
    :workflow: Windows

.. coveralls-shield::

Shield to show the code coverage from Coveralls.io.

:username:

The GitHub username. Defaults to github_username.

:repository:

The GitHub repository. Defaults to github_repository.

:branch:

The branch to show the build status for. Default master.

Example

.. coveralls-shield::

.. codefactor-shield::

Shield to show the code quality score from Codefactor.

:username:

The GitHub username. Defaults to github_username.

:repository:

The GitHub repository. Defaults to github_repository.

Example

.. codefactor-shield::

.. pre-commit-shield::

Shield to indicate that the project uses pre-commit.

Example

.. pre-commit-shield::

.. pre-commit-ci-shield::

New in version 1.7.0.

Shield to show the pre-commit.ci status.

:username:

The GitHub username. Defaults to github_username.

:repository:

The GitHub repository. Defaults to github_repository.

:branch:

The branch to show the status for. Default master.

Example

.. pre-commit-ci-shield::

Data:

SHIELDS_IO	Base URL for shields.io
shield_default_option_spec	Options common to all shields.

Classes:

Shield(name, arguments, options, content, ...)	Directive for shields.io shields/badges.
RTFDShield(name, arguments, options, ...)	Shield to show the ReadTheDocs documentation build status.
PyPIShield(name, arguments, options, ...)	Shield to show information about the project on PyPI.
MaintainedShield(name, arguments, options, ...)	Shield to indicate whether the project is maintained.
GitHubBackedShield(name, arguments, options, ...)	Base class for badges that are based around GitHub.
GitHubShield(name, arguments, options, ...)	Shield to show information about a GitHub repository.
GitHubActionsShield(name, arguments, ...)	Shield to show the GitHub Actions build status.
RequiresIOShield(name, arguments, options, ...)	Shield to show the Requires.io status.
CoverallsShield(name, arguments, options, ...)	Shield to show the code coverage from Coveralls.io.
CodefactorShield(name, arguments, options, ...)	Shield to show the code quality score from Codefactor.
PreCommitShield(name, arguments, options, ...)	Shield to indicate that the project uses pre-commit.
PreCommitCIShield(name, arguments, options, ...)	Shield to show the pre-commit.ci status.

Functions:

copy_asset_files(app[, exception])	Copy additional stylesheets into the HTML build directory.
setup(app)	Setup sphinx_toolbox.shields.

API Reference

SHIELDS_IO = URL('https://img.shields.io')

Type:    URL

Base URL for shields.io

shield_default_option_spec

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

Options common to all shields.

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

Bases: SphinxDirective

Directive for shields.io shields/badges.

required_arguments = 1

Type:    int

optional_arguments = 0

Type:    int

final_argument_whitespace = True

Type:    bool

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'scale': <function percentage>, 'target': <function unchanged_required>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: Shield

Shield to show the ReadTheDocs documentation build status.

Changed in version 1.8.0: Added the :target: option, to allow a custom target to be specified. Useful if the documentation uses a custom domain.

required_arguments = 0

Type:    int

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'project': <function unchanged_required>, 'scale': <function percentage>, 'target': <class 'str'>, 'version': <class 'str'>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: Shield

Shield to show information about the project on PyPI.

required_arguments = 0

Type:    int

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'downloads': <class 'str'>, 'height': <function length_or_unitless>, 'implementations': <function flag>, 'license': <function flag>, 'name': <function unchanged>, 'project': <function unchanged_required>, 'py-versions': <function flag>, 'scale': <function percentage>, 'version': <function flag>, 'wheel': <function flag>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: Shield

Shield to indicate whether the project is maintained.

required_arguments = 1

Type:    int

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'scale': <function percentage>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: Shield

Base class for badges that are based around GitHub.

required_arguments = 0

Type:    int

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'repository': <class 'str'>, 'scale': <function percentage>, 'username': <class 'str'>, 'width': <function length_or_percentage_or_unitless>}

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

get_repo_details()

Returns the username and repository name, either parsed from the directive’s options or from conf.py.

Return type:

Tuple[str, str]

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

Bases: GitHubBackedShield

Shield to show information about a GitHub repository.

option_spec = {'alt': <function unchanged>, 'branch': <class 'str'>, 'class': <function class_option>, 'commits-since': <class 'str'>, 'contributors': <function flag>, 'height': <function length_or_unitless>, 'last-commit': <function flag>, 'license': <function flag>, 'name': <function unchanged>, 'repository': <class 'str'>, 'scale': <function percentage>, 'top-language': <function flag>, 'username': <class 'str'>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: GitHubBackedShield

Shield to show the GitHub Actions build status.

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'repository': <class 'str'>, 'scale': <function percentage>, 'username': <class 'str'>, 'width': <function length_or_percentage_or_unitless>, 'workflow': <function unchanged_required>}

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

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

Bases: GitHubBackedShield

Shield to show the Requires.io status.

Deprecated since version The: requires.io service has shut down.

option_spec = {'alt': <function unchanged>, 'branch': <class 'str'>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'repository': <class 'str'>, 'scale': <function percentage>, 'username': <class 'str'>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: GitHubBackedShield

Shield to show the code coverage from Coveralls.io.

option_spec = {'alt': <function unchanged>, 'branch': <class 'str'>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'repository': <class 'str'>, 'scale': <function percentage>, 'username': <class 'str'>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: GitHubBackedShield

Shield to show the code quality score from Codefactor.

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

Bases: Shield

Shield to indicate that the project uses pre-commit.

required_arguments = 0

Type:    int

option_spec = {'alt': <function unchanged>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'scale': <function percentage>, 'width': <function length_or_percentage_or_unitless>}

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

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

Bases: GitHubBackedShield

Shield to show the pre-commit.ci status.

New in version 1.7.0.

option_spec = {'alt': <function unchanged>, 'branch': <class 'str'>, 'class': <function class_option>, 'height': <function length_or_unitless>, 'name': <function unchanged>, 'repository': <class 'str'>, 'scale': <function percentage>, 'username': <class 'str'>, 'width': <function length_or_percentage_or_unitless>}

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

copy_asset_files(app, exception=None)

Copy additional stylesheets into the HTML build directory.

New in version 2.3.1.

Parameters:

• app (Sphinx) – The Sphinx application.

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

setup(app)

Setup sphinx_toolbox.shields.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata