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, like this one:
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.
-
: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
-
-
.. 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
-
-
.. 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
andlast-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
-
-
.. 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
-
-
.. 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
-
-
.. 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
-
-
.. 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
-
-
.. pre-commit-shield::
¶ Shield to indicate that the project uses pre-commit.
Example
-
.. 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
-
Data:
Base URL for shields.io |
|
Options common to all shields. |
Classes:
|
Directive for shields.io shields/badges. |
|
Shield to show the ReadTheDocs documentation build status. |
|
Shield to show information about the project on PyPI. |
|
Shield to indicate whether the project is maintained. |
|
Base class for badges that are based around GitHub. |
|
Shield to show information about a GitHub repository. |
|
Shield to show the GitHub Actions build status. |
|
Shield to show the Requires.io status. |
|
Shield to show the code coverage from Coveralls.io. |
|
Shield to show the code quality score from Codefactor. |
|
Shield to indicate that the project uses pre-commit. |
|
Shield to show the pre-commit.ci status. |
Functions:
|
Copy additional stylesheets into the HTML build directory. |
|
Setup |
API Reference¶
-
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.
-
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.
-
setup
(app)[source]¶ Setup
sphinx_toolbox.shields
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type