shields

The shields directive renders a project’s badges from shields.io - where the project lives, how it is licensed, whether it builds, where it is published.

The options state the project’s coordinates: its GitHub repository, its PyPI package, its licenses, its workflow and its documentation’s URL. The content names the badges and is the layout: badges appear in the order written, and each line is a row.

A badge needs only the options it is made of, so a project states what its badges use and nothing else.

.. shields::
   :github:                pyTooling/pyTooling
   :pypi:                  pyTooling
   :codacy:                08ef744c0b70490289712b02a7a4cebe
   :source-license:        github:LICENSE.md
   :documentation-license: CC-BY-4.0 github:doc/Doc-License.rst
   :github-action:         Pipeline.yml@main
   :documentation:         github-pages

   github, src-license, ghp-doc, doc-license
   pypi-tag, pypi-status, pypi-python
   github-action, lib-status, codacy-quality, codacy-coverage, codecov-coverage

This is how the example renders:

Options

.. shields::

Renders a project’s badges, in rows. Each line of the content is a row of badge identifiers, separated by commas.

:github: <organization>/<repository>: The GitHub repository, for the badges showing it and for github: links.

:pypi: <package>: The package’s name on PyPI.

:codacy: <project ID>: The Codacy project ID, as shown in Codacy’s badge settings.

:gitter: <room>: The Gitter room, e.g. hdl/community.

:source-license: [<SPDX expression> ]<link>: Where the source code’s license is written. Without a license before the link, the badge shows what PyPI reports for the package when shields:pypi is stated, and what GitHub reports for the repository otherwise.

:documentation-license: <SPDX expression> <link>: The documentation’s license and where it is written. The license is required: nothing reports a documentation’s license.

:github-action: <workflow file>[@<branch>]: The workflow whose status is shown. Without a branch, the badge shows the workflow’s latest run on any branch.

:documentation: github-pages | <URL>: Where the documentation is published. github-pages is the GitHub Pages site of shields:github; any other value is an http:// or https:// URL.

:class: <CSS classes>: Additional CSS classes on the rows.

Links

shields:source-license and shields:documentation-license end in a link, which is one of:

github:<path>: → the file at <path> on the default branch of the repository shields:github names.
http://… or https://…: → used as written.

Licenses

A license is an SPDX license expression, parsed by LicenseExpression.Parse(): Apache-2.0, CC-BY-4.0 or MIT OR Apache-2.0. A misspelt identifier is reported. A license that isn’t on the SPDX License List is written LicenseRef-<name>.

Badges

Identifier	Shows	Options
`github`	the repository	`github`
`src-license`	the source code’s license	`source-license`
`doc-license`	the documentation’s license	`documentation-license`
`ghp-doc`	whether the documentation is online	`documentation`
`tag`	the latest tag, including pre-releases	`github`
`date`	the date of the latest release	`github`
`github-action`	the workflow’s status	`github`, `github-action`
`codacy-quality`	Codacy’s code quality grade	`github`, `codacy`
`codacy-coverage`	Codacy’s line coverage	`github`, `codacy`
`codecov-coverage`	Codecov’s branch coverage	`github`
`pypi-tag`	the latest version on PyPI	`pypi`
`pypi-status`	the development status on PyPI	`pypi`
`pypi-python`	the Python versions on PyPI	`pypi`
`lib-status`	whether the dependencies are up to date, by Libraries.io	`pypi`
`lib-rank`	the SourceRank, by Libraries.io	`pypi`
`lib-dep`	how many repositories depend on the package	`github`, `pypi`
`gitter`	a link to the Gitter room	`gitter`

A github: link, a license GitHub reports, and github-pages need shields:github as well.

HTML and LaTeX

The directive emits both variants, each wrapped in an only node: HTML embeds the SVG from img.shields.io, LaTeX the PNG from raster.shields.io - a PDF cannot embed an SVG.

Errors

A mistake is reported on the page, where the badges would be, and in the build’s log:

shields: 'gha-test' is not a known badge. Known are: codacy-coverage, codacy-quality, codecov-coverage, ...
shields: Badge 'pypi-tag' needs option ':pypi:'.
shields: Option ':github:' is 'pyTooling', not '<organization>/<repository>'.
shields: Option ':source-license:' links to 'LICENSE.md', neither 'github:<path>' nor a URL.
shields: Option ':documentation-license:' states 'CC-BY-5.0', which isn't an SPDX license expression.