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. The first release is v1.0.0, a stable one (Production/Stable).
Python 3.12 to 3.15 (Sphinx 9.1 requires Python 3.12) and pyTooling 10.1; the extras
reports (pyEDAA.Reports 1.0) 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 dependency-table lists the build requirements of a pyproject.toml file,
declared with the entrypoint field pyproject; the file is found in the project’s root directory,
pyTooling_ProjectRoot.
A dependency-table folds the dependencies of a duplicate - a package an earlier
line already shows - below a link to that line (:duplicates:, :duplicate-match:), and names a package’s
extras: pyTooling[dependencies].
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 project derives its own unit test table from
UnittestSummaryBase, its columns declared as
Column and ColumnGroup; its pages
extend UnittestReportPages, and a domain of its own with roles of its
own derives from ReportDomain.
A unit test summary explains its status symbols in a legend below the
table; :legend: draws it above the table or leaves it out.
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.