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