.. _DIR/Shields: shields ####### .. grid:: 2 .. grid-item:: :columns: 6 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. .. grid-item:: :columns: 6 .. code-block:: ReST .. 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: .. 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 .. _DIR/Shields/Options: Options ******* .. rst:directive:: .. shields:: Renders a project's badges, in rows. Each line of the content is a row of badge identifiers, separated by commas. .. rst:directive:option:: github: / The GitHub repository, for the badges showing it and for ``github:`` links. .. rst:directive:option:: pypi: The package's name on PyPI. .. rst:directive:option:: codacy: The Codacy project ID, as shown in Codacy's badge settings. .. rst:directive:option:: gitter: The Gitter room, e.g. ``hdl/community``. .. rst:directive:option:: source-license: [ ] Where the source code's license is written. Without a license before the link, the badge shows what PyPI reports for the package when :rst:dir:`shields:pypi` is stated, and what GitHub reports for the repository otherwise. .. rst:directive:option:: documentation-license: The documentation's license and where it is written. The license is required: nothing reports a documentation's license. .. rst:directive:option:: github-action: [@] The workflow whose status is shown. Without a branch, the badge shows the workflow's latest run on any branch. .. rst:directive:option:: documentation: github-pages | Where the documentation is published. ``github-pages`` is the GitHub Pages site of :rst:dir:`shields:github`; any other value is an ``http://`` or ``https://`` URL. .. rst:directive:option:: class: Additional CSS classes on the rows. .. rubric:: Links :rst:dir:`shields:source-license` and :rst:dir:`shields:documentation-license` end in a link, which is one of: ``github:`` |rarr| the file at ```` on the default branch of the repository :rst:dir:`shields:github` names. ``http://…`` or ``https://…`` |rarr| used as written. .. rubric:: Licenses A license is an `SPDX license expression `__, parsed by :meth:`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-``. .. _DIR/Shields/Badges: Badges ****** .. list-table:: :header-rows: 1 :widths: 20 45 35 * - 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 :rst:dir:`shields:github` as well. .. _DIR/Shields/Output: HTML and LaTeX ************** The directive emits both variants, each wrapped in an :rst:dir:`only` node: HTML embeds the SVG from ``img.shields.io``, LaTeX the PNG from ``raster.shields.io`` - a PDF cannot embed an SVG. .. _DIR/Shields/Errors: Errors ****** A mistake is reported on the page, where the badges would be, and in the build's log: .. code-block:: text 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 '/'. shields: Option ':source-license:' links to 'LICENSE.md', neither 'github:' nor a URL. shields: Option ':documentation-license:' states 'CC-BY-5.0', which isn't an SPDX license expression.