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
https://img.shields.io/readthedocs/sphinx-toolbox/latest?logo=read-the-docs

.. rtfd-shield::
    :project: attrs
    :target: https://www.attrs.org/
https://img.shields.io/readthedocs/attrs/latest?logo=read-the-docs

.. 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
https://img.shields.io/pypi/v/sphinx-toolbox

https://img.shields.io/pypi/dm/sphinx

.. maintained-shield::

Shield to indicate whether the project is maintained.

Takes a single argument: the current year.

Example

.. maintained-shield:: 2020
https://img.shields.io/maintenance/yes/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
https://img.shields.io/github/last-commit/sphinx-toolbox/sphinx-toolbox/master

https://img.shields.io/github/commits-since/sphinx-toolbox/sphinx-toolbox/v0.1.0/master

.. 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 Tests
https://github.com/sphinx-toolbox/sphinx-toolbox/workflows/Windows%20Tests/badge.svg

.. requires-io-shield::

Shield to show the Requires.io status.

: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

.. requires-io-shield::
https://requires.io/github/sphinx-toolbox/sphinx-toolbox/requirements.svg?branch=master

.. 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::
https://img.shields.io/coveralls/github/sphinx-toolbox/sphinx-toolbox/master?logo=coveralls

.. 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::
https://img.shields.io/codefactor/grade/github/sphinx-toolbox/sphinx-toolbox?logo=codefactor

.. pre-commit-shield::

Shield to indicate that the project uses pre-commit.

Example

.. pre-commit-shield::
https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white

.. 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::
https://results.pre-commit.ci/badge/github/sphinx-toolbox/sphinx-toolbox/master.svg

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)[source]

Bases: SphinxDirective

Directive for shields.io shields/badges.

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

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.

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

Bases: Shield

Shield to show information about the project on PyPI.

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

Bases: Shield

Shield to indicate whether the project is maintained.

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

Bases: Shield

Base class for badges that are based around GitHub.

get_repo_details()[source]

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)[source]

Bases: GitHubBackedShield

Shield to show information about a GitHub repository.

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

Bases: GitHubBackedShield

Shield to show the GitHub Actions build status.

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

Bases: GitHubBackedShield

Shield to show the Requires.io status.

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

Bases: GitHubBackedShield

Shield to show the code coverage from Coveralls.io.

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

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)[source]

Bases: Shield

Shield to indicate that the project uses pre-commit.

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

Bases: GitHubBackedShield

Shield to show the pre-commit.ci status.

New in version 1.7.0.

copy_asset_files(app, exception=None)[source]

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)[source]

Setup sphinx_toolbox.shields.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata