---

The pyTooling.Sphinx Documentation

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, tables of icons, 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.

Attention

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.

For LaTeX, it sets two configuration values, unless conf.py sets them:

latex_table_style

→ ["booktabs"]. Sphinx’ default adds colorrows, which stops a PDF build with MiKTeX in the first table (TeX capacity exceeded).

latex_elements["maxlistdepth"]

→ "10". LaTeX nests lists at most 4 levels deep, and a tree is a nested list.

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.

unicode-table

→ Icons with their Unicode names and code points, computed from the icons; in HTML, a button copies an icon or its code points. Common Icons lists icons commonly used in a tree.

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.

Links

External link icons

→ In HTML, an icon behind each external link, chosen by its target: e.g. GitHub’s mark, Python’s logo, an envelope for an e-mail address.

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).