pyTooling.Sphinx

pyTooling.Sphinx adds roles and directives to Sphinx: styled inline text and line breaks working in HTML and LaTeX, condensed class interfaces, dependency tables generated from requirements files and the package index, badges, schema graphs, trees, lists of abbreviations, and unit test and coverage reports.

Other packages build on it: pyTooling.GitHub contributes the domain ghactions for GitHub Actions workflows, enabled as the extension pyTooling.GitHub.Sphinx.

Important

pyTooling.Sphinx requires Python 3.12 or newer, because it requires Sphinx 9.1 and Sphinx 9.1 does.

The extension is enabled in conf.py:

# doc/conf.py
extensions = [
  ...,
  "pyTooling.Sphinx",
]

It links its stylesheet into every HTML page, appends its substitutions to rst_prolog, and sets up sphinx.ext.graphviz for the schema graphs.

The domain report - unit test, code coverage and documentation coverage reports as tables - reads the reports with pyEDAA.Reports, an optional dependency. A project using a report installs it with the extra reports:

pip install pyTooling.Sphinx[reports]

Roles and Directives

Roles

• Style roles - :red:, :underline:, :deletion: and more: CSS classes on inline text, with the stylesheet giving them their meaning.
• Inline Python code - :pycode:, syntax-highlighted inline code.
• Line break and horizontal rule - |br| and |hr|, in HTML and LaTeX.

Directives

• condensed-class - A class' public interface as one code block, parsed from its source.
• dependency-table - A project's dependencies with versions and licenses, from its requirements files and the package index.
• jsonschema-graph - Planned: a JSON schema as a Graphviz graph.
• xmlschema-graph - An XML schema as a Graphviz graph, drawn from the schema file.
• shields - A project's badges from shields.io, in rows.
• tree - A hierarchy, written as an indented list, drawn as a tree with foldable nodes.
• abbreviations - A list of abbreviations, referred to by :acs:, :acl:, :acf: and their plurals; in HTML, a short form explains itself on hover.

Directives of domain report (extra reports)

• report:unittest-summary - A unit test report in JUnit XML or pyTooling's XML format, per testsuite and testcase; optionally with a page per testsuite and testcase, referred to by the roles :ts: and :tc:.
• report:code-coverage - A code coverage report in Cobertura XML or coverage.py's JSON format, per directory and source file, and a legend of its coverage levels; optionally with a page per directory and source file showing a file's highlighted source, each line marked by its coverage, referred to by the role :cov:.
• report:doc-coverage - A package's documentation coverage, per package and module, and a legend of its coverage levels.

Consumers

This layer is used by:

• pyTooling.GitHub - its Sphinx domain ghactions builds on this extension, and its documentation uses it.
• 🚧 pyTooling - its documentation, which still uses pyTooling's own copy of this extension.

Contributors

• Patrick Lehmann (Maintainer)
• and more...

License

This Python package (source code) is licensed under Apache License 2.0.
The accompanying documentation is licensed under Creative Commons - Attribution 4.0 (CC-BY 4.0).
Content of other projects - e.g. GitHub's emoji table from github/gemoji (MIT) - is listed with its license in NOTICE.md.

---

SPDX-License-Identifier: Apache-2.0