# ==================================================================================================================== #
# _____ _ _ ____ _ _ #
# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___| _ __ | |__ (_)_ __ __ __ #
# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` | \___ \| '_ \| '_ \| | '_ \\ \/ / #
# | |_) | |_| || | (_) | (_) | | | | | | (_| |_ ___) | |_) | | | | | | | |> < #
# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____/| .__/|_| |_|_|_| |_/_/\_\ #
# |_| |___/ |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2026-2026 Patrick Lehmann - Bötzingen, Germany #
# #
# Licensed under the Apache License, Version 2.0 (the "License"); #
# you may not use this file except in compliance with the License. #
# You may obtain a copy of the License at #
# #
# http://www.apache.org/licenses/LICENSE-2.0 #
# #
# Unless required by applicable law or agreed to in writing, software #
# distributed under the License is distributed on an "AS IS" BASIS, #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
# See the License for the specific language governing permissions and #
# limitations under the License. #
# #
# SPDX-License-Identifier: Apache-2.0 #
# ==================================================================================================================== #
#
"""
The docutils nodes pyTooling.Sphinx adds, and what registering one with Sphinx takes.
A node is a class here; the functions writing it are in a module per output format - :mod:`~pyTooling.Sphinx.HTML`
and :mod:`~pyTooling.Sphinx.LaTeX` - and :data:`~pyTooling.Sphinx.NODES` pairs both for :func:`~pyTooling.Sphinx.setup`.
A node without visitors for a format is written by the visitors of its base-class there.
"""
from typing import Any, Callable, NotRequired, TypedDict
from docutils import nodes
from pyTooling.Decorators import export
__all__ = ["visitFunc", "departFunc", "COVERAGE_STATES", "DOCUMENTATION_STATES"]
#: The coverage states of a listing's lines, as the listing's legend names them, by state; ``""`` for a line, which
#: isn't executable.
COVERAGE_STATES = {
"covered": "covered",
"partial": "partial",
"uncovered": "uncovered",
"excluded": "excluded",
"": "not executable",
}
#: The documentation states of a condensed listing's lines, as the listing's legend names them, by state; ``""`` for a
#: line, whose documentation isn't counted.
DOCUMENTATION_STATES = {
"documented": "documented",
"undocumented": "undocumented",
"ignored": "ignored",
"excluded": "excluded",
"": "not counted",
}
type visitFunc = Callable[[Any, Any], Any]
"""A function writing the start of a node: called with the translator and the node."""
type departFunc = Callable[[Any, Any], Any]
"""A function writing the end of a node: called with the translator and the node."""
[docs]
@export
class RegisteredNode(TypedDict):
"""An entry of :data:`~pyTooling.Sphinx.NODES`: a node class, and its visitors per output format."""
name: str #: Name of the node.
node: type[nodes.Element] #: The node class to register.
html: tuple[visitFunc, departFunc] #: Visit and depart function writing the node in HTML.
latex: NotRequired[tuple[visitFunc, departFunc]] #: Visit and depart function writing the node in LaTeX, if any.
[docs]
@export
class TreeItem(nodes.list_item):
"""
An entry of a tree: a list item, which HTML draws around a ``<details>`` element if the entry has children.
Attribute ``expanded`` states whether the entry is expanded initially, and is ``None`` if it has no children.
Attribute ``columnWidth`` holds the width of the column of the entries' texts as a CSS length, measured from the
tree's left edge, if the entry is a root of a tree with descriptions; else ``None``.
"""
[docs]
@export
class TreeLabel(nodes.paragraph):
"""
An entry's text: a paragraph, which HTML draws as the ``<summary>`` of the entry's ``<details>`` element.
Attribute ``icon`` holds the icon of the entry's kind, ``expandedIcon`` and ``collapsedIcon`` the icons showing
whether the entry is expanded. Both are ``None`` if the entry has no children. Attribute ``level`` holds the entry's
level, ``0`` for a root, and ``descriptionColumn`` whether the tree has descriptions: then HTML draws the entry as
a row of two columns, whether this entry has a description or not.
An entry's description follows its text, as a :class:`TreeSeparator` and a :class:`TreeDescription`.
"""
[docs]
@export
class TreeSeparator(nodes.inline):
"""
The separator between an entry's text and its description: an en dash, which HTML skips.
HTML draws the description in a column of its own. Every other format - e.g. LaTeX - writes its base-class, so the
description follows the text in the same line: ``text – description``.
"""
[docs]
@export
class TreeDescription(nodes.inline):
"""
An entry's description, which HTML draws in a column of its own: all descriptions of a tree start at the same
horizontal position, whatever the entry's level.
"""
[docs]
@export
class TreeLegend(nodes.paragraph):
"""
A tree's legend: a paragraph of :class:`TreeLegendItem` nodes, which HTML draws as one line above or below the tree.
Formats drawing no icons in a tree don't get it: :class:`~pyTooling.Sphinx.Tree.RemoveTreeLegends` removes it.
"""
[docs]
@export
class TreeLegendItem(nodes.inline):
"""
An item of a tree's legend: the text explaining an icon. Attribute ``icon`` holds the icon.
"""
[docs]
@export
class Abbreviation(nodes.abbreviation):
"""
A reference to an abbreviation in its short form, which HTML draws with a box explaining it on hover.
Attributes ``short`` and ``long`` hold the abbreviation's forms, even if the node's text is a title the role was
written with; ``summary`` holds the summary of its description the box shows, or an empty string. The attribute
``explanation`` of the base-class is left unset: LaTeX and text would append it in parentheses, and an abbreviation
is written in the form its role asks for.
"""
[docs]
@export
class Landscape(nodes.container):
"""
A container whose content LaTeX puts on landscape pages; HTML writes the content only.
A wide table is such content.
LaTeX's ``landscape`` environment needs package ``pdflscape``, which :func:`~pyTooling.Sphinx.setup` requests. The
report tables of domain ``report`` are what this node holds.
"""
[docs]
@export
class CoverageListing(nodes.literal_block):
"""
A source file's code coverage: its lines, syntax highlighted, each marked by its coverage state.
Attribute ``lines`` holds a tuple per line: the line number, the state (``covered``, ``partial``, ``uncovered``,
``excluded``, or ``""`` for a line, which isn't executable), the hits or ``None``, the number of branches and of
taken branches, and the line's tokens as ``(CSS class, text)`` pairs - the short classes of Pygments' token types,
which Sphinx' Pygments stylesheet colors. Attribute ``anchors`` states whether a line gets the ID ``L<number>``.
Attribute ``path`` holds the file's path in the report, which the listing's header shows beside the legend of the
coverage states.
The node's text is the plain source, so a builder without visitors for this node writes it as a literal block.
"""
[docs]
@export
class DocCoverageListing(nodes.literal_block):
"""
A Python module's documentation coverage: its condensed source, syntax highlighted, each line marked by its
documentation state.
The source is condensed to what is documented: a function's or class' decorators, its header and its doc-string,
fields and variables; a body is elided to one ``...`` line.
Attribute ``lines`` holds a tuple per line: the line number - ``None`` for an elided body's ``...`` -, the state
(``documented``, ``undocumented``, ``ignored``, ``excluded``, or ``""`` for a line, whose documentation isn't
counted), and the line's tokens as ``(CSS class, text)`` pairs - the short classes of Pygments' token types, which
Sphinx' Pygments stylesheet colors. Attribute ``path`` holds the module's path, which the listing's header shows
beside the legend of the documentation states.
The node's text is the condensed source, so a builder without visitors for this node writes it as a literal block.
"""
[docs]
@export
class Emoji(nodes.inline):
"""
An emoji: its characters, which HTML draws with its shortcode as tooltip.
Attribute ``shortcode`` holds the emoji's GitHub shortcode without colons, e.g. ``tada``. LaTeX writes its base-class,
so the characters as they are - LuaLaTeX draws them with a Unicode emoji font, which e.g. :file:`pytooling.sty` of
the MiKTeX image maps them to.
"""
[docs]
@export
class TaskListCheckbox(nodes.inline):
"""
The checkbox opening a task list item, which HTML draws as a disabled checkbox.
Attribute ``checked`` states whether the task is done. The node's text is a ballot box, with check if the task is
done, so a format writing its base-class - an inline element - writes that character. LaTeX writes a box symbol.
"""
[docs]
@export
class ReportIndentation(nodes.inline):
"""
The name of an entry in a report table, indented by the entry's depth: HTML as a padding, LaTeX by a macro.
Attribute ``level`` holds the number of indentation steps, e.g. ``2`` for a testcase in a testsuite. A wrapped name
stays at its indentation. A format writing its base-class - an inline element - writes the name without indentation.
"""
[docs]
@export
class LineBreak(nodes.inline):
"""
A line break inside a paragraph, which HTML writes as ``<br />`` and LaTeX as ``\\newline``.
The node's text is a newline, so a format writing its base-class - an inline element - writes a space.
"""