First release: pyTooling’s Sphinx extension pyTooling.Sphinx becomes a package of its own. It was
developed in the dev branch of pyTooling and moved here before any pyTooling release
contained it.
Python 3.12 to 3.15 (Sphinx 9.1 requires Python 3.12); the extras reports and
markdown install the optional requirements.
Roles: style roles, inline Python code, and
line break and horizontal rule in HTML and LaTeX.
Directives: condensed-class,
dependency-table, xmlschema-graph,
shields, tree and abbreviations with the
abbreviation roles :acs:, :acl:, :acf: and their plurals.
A dependency-table limited by :depth: marks each package whose dependencies
weren’t expanded.
A dependency-table reports a broken requirement line, also one in a file included
with -r, a warning of a release’s details and a warning from loading a project as a Sphinx warning. A package
whose license needs an override is reported once, by its canonical name - the key the override file is looked up
by.
A dependency-table resolves the requirements with pyTooling’s
Resolver, which downloads the packages of one level in parallel; a
requirement naming extras lists their requirements too.
A tree explains its icons in a legend: an icon option takes a text
behind a |, and :legend: draws the legend above or below the tree.
A tree entry may have a description behind a |, drawn as a
second, aligned column.
Directive unicode-table: icons with their Unicode names and code points, computed with
unicodedata; in HTML, a button copies an icon or its code points into the clipboard. It lists the
icons commonly used in a tree. A tree’s icon option rejects a surrogate code point.
DotGraph is built on pyTooling.Graph.GraphViz.
xmlschema-graph draws a schema shipped in a package with the option :package:.
Domain report from sphinx-reports (v0.11.2), with the directives
report:unittest-summary, report:code-coverage and
report:doc-coverage. Reading a report needs the extra reports.
The domain report takes part in a parallel build (sphinx-build -j N).
A package’s levels may be a palette of its own, a dictionary checked like the palettes in
pyTooling_CodeCoverage_Levels or pyTooling_DocCoverage_Levels.
A unit test report declared with pages gets a
page per testsuite and testcase, generated without source files, linked
from the summary table and listed in the navigation below the summary’s page, and the roles
:tc: and :ts: refer to them. A report may be in
pyTooling’s XML format too.
A code coverage report is read with pyEDAA.Reports’ language-neutral model, from
Cobertura XML or coverage.py’s JSON report, and shown per directory and source
file. Declared with pages and sources, it gets a
page per directory and source file; a file’s page shows its source, syntax
highlighted with Pygments, each line marked by its coverage state. The role
:cov: refers to a page, optionally to a line, and the directive
report:file-coverage shows a file’s listing anywhere.
A package’s documentation coverage is analyzed by pyEDAA.Reports’
language-neutral model and its Python reader, which counts fields and variables too; docstr_coverage isn’t
needed anymore. A package declared with pages gets a
page per package and module; a module’s page shows its source condensed to the
decorators, signatures and doc-strings of its classes and functions - bodies elided to ... - and its fields
and variables, each marked by its documentation state. The role :doccov: refers to
a page.
External link icons: in HTML, an icon behind each external link, chosen by its target -
GitHub’s mark, GitLab’s tanuki, the logos of Python, NumPy, PyPy, pytest, Pydantic, Read the Docs and
Sphinx, an envelope for an e-mail address, or a square with an arrow; a link of the :download: role gets a
download icon, a link to an archive an archive icon. The configuration value pyTooling_ExternalLink_Icons
adds the intersphinx links or disables the icons, and pyTooling_ExternalLink_Hosts adds hosts. A link with an
icon opens in a new browser tab, unless pyTooling_ExternalLink_NewTab is False.
Download sizes: a download’s file size follows its link, for an archive with its
format, e.g. (ZIP, 1.2 MiB); another site’s file is asked for with an HTTP HEAD request, if its URI matches
a pattern of pyTooling_ExternalLink_RemoteSizes. pyTooling_ExternalLink_DownloadSizes switches the sizes
off, pyTooling_ExternalLink_RemoteSizeTimeout sets the time to wait for an answer.
pyTooling.Sphinx.GitHubMarkdown converts GitHub-flavoured Markdown into docutils nodes - GitHub alerts as
admonitions, task lists, tables, footnotes, linked GitHub references and emoji -, installed with the extra
markdown.
For LaTeX, latex_table_style defaults to ["booktabs"] and latex_elements["maxlistdepth"] to "10",
unless conf.py or -D sets them.
⚠️ The domain is registered by the extension pyTooling.Sphinx instead of sphinx_reports; it is still
report.
⚠️ The configuration values are renamed: report_unittest_testsuites → pyTooling_Unittest_Testsuites,
report_codecov_packages/report_codecov_levels →
pyTooling_CodeCoverage_Packages/pyTooling_CodeCoverage_Levels, and
report_doccov_packages/report_doccov_levels →
pyTooling_DocCoverage_Packages/pyTooling_DocCoverage_Levels.
⚠️ report:dependency-table is dropped in favour of dependency-table.
⚠️ report:code-coverage shows directories and files instead of Python packages and modules, and reads
Cobertura XML too; the prototype report:module-coverage is replaced by
report:file-coverage.
The report styles are part of the stylesheet of pyTooling.Sphinx, and a theme’s row stripes are reset for
the report tables only, no longer for every table.
A report table indents a name by markup instead of em quads, so a wrapped name stays at its indentation and a
copied name has no leading spaces; --pyTooling-report-indentation (HTML) and
\pyToolingReportIndentationStep (LaTeX) set the step.
A legend in style horizontal-table renders.
An invalid levels is reported with a message; it was empty.