sphinx-structured-toc 0.1.0__py3-none-any.whl

sphinx_structured_toc/__init__.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
+from .directives import DomainDirective, SliceDirective
+from .html import (
+    depart_domain,
+    depart_slice,
+    depart_slice_item,
+    visit_domain,
+    visit_slice,
+    visit_slice_item,
+)
+from .nodes import Domain, Slice, SliceItem
+from .transforms import resolve_domains
+
+_CSS_DIR = str(Path(__file__).parent)
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("sphinx-structured-toc")
+    except PackageNotFoundError:
+        __version__ = "dev"
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    # register various components
+
+    # nodes
+    app.add_node(Domain, html=(visit_domain, depart_domain))
+    app.add_node(Slice, html=(visit_slice, depart_slice))
+    app.add_node(SliceItem, html=(visit_slice_item, depart_slice_item))
+
+    # directives
+    app.add_directive("domain", DomainDirective)
+    app.add_directive("slice", SliceDirective)
+
+    # transform
+    app.connect("doctree-resolved", resolve_domains)
+
+    # static asset shipping
+    app.connect("builder-inited", add_static_dir)
+
+    # reference override (decorates <a> emitted for marked slice items)
+    app.connect("builder-inited", install_reference_override)
+
+    app.add_css_file("domain-list.css")
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
+
+
+def add_static_dir(app: Sphinx) -> None:
+    """Add the extension package directory to ``html_static_path``."""
+
+    if _CSS_DIR not in app.config.html_static_path:
+        app.config.html_static_path.append(_CSS_DIR)
+
+
+def install_reference_override(app: Sphinx) -> None:
+    """Override ``docutils.nodes.reference`` HTML visitors."""
+
+    from docutils import nodes as docutils_nodes
+
+    from .html import make_reference_visitor
+
+    visit, depart = make_reference_visitor(app)
+    app.add_node(
+        docutils_nodes.reference,
+        html=(visit, depart),
+        override=True,
+    )
+
+
+__all__ = ["__version__", "setup"]

sphinx_structured_toc/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g8833e90'

sphinx_structured_toc/directives.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from docutils import nodes
+from docutils.parsers.rst.directives import flag
+from sphinx.addnodes import pending_xref
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import OptionSpec
+
+from .nodes import Domain, Slice, SliceItem
+
+
+class DomainDirective(SphinxDirective):
+    """Outer directive: ``.. domain::`` with an optional name argument."""
+
+    optional_arguments = 1
+    final_argument_whitespace = True  # allow whitespace in the name
+    has_content = True  # has content that will need to be parsed
+    option_spec: ClassVar[OptionSpec] = {"suppress-warnings": flag}
+
+    def run(self) -> list[nodes.Node]:
+        """Parse nested content and validate that only Slice children result."""
+        overridden = bool(self.arguments)
+
+        # if not supplied the name will need to be resolved later
+        name = self.arguments[0] if overridden else ""
+
+        nested = nodes.Element()
+        # parse the inner content
+        self.state.nested_parse(self.content, self.content_offset, nested)
+
+        # if slice parsing fails, forward the first error
+        messages = [c for c in nested.children if isinstance(c, nodes.system_message)]
+        if messages:
+            return [messages[0]]
+
+        slices = [child for child in nested.children if isinstance(child, Slice)]
+        non_slice = [child for child in nested.children if not isinstance(child, Slice)]
+
+        if non_slice:
+            return [self.emit_error("domain may only contain 'slice' blocks")]
+
+        if not slices:
+            return [self.emit_error("domain must contain at least one slice")]
+
+        # create the node, pass its attributes, add the slices
+        domain_node = Domain()
+        if overridden:
+            domain_node["name"] = name
+        domain_node["overridden"] = overridden
+        if "suppress-warnings" in self.options:
+            domain_node["suppress_warnings"] = True
+        domain_node.extend(slices)
+        return [domain_node]
+
+    def emit_error(self, msg: str) -> nodes.system_message:
+        return self.state_machine.reporter.error(
+            msg,
+            nodes.literal_block(self.block_text, self.block_text),
+            line=self.lineno,
+        )
+
+
+class SliceDirective(SphinxDirective):
+    """Inner directive: ``.. slice:: <name>`` with item lines as content."""
+
+    required_arguments = 1
+    final_argument_whitespace = True
+    has_content = True
+    option_spec: dict = {}
+
+    def run(self) -> list[nodes.Node]:
+        """Build a Slice node from the directive content."""
+
+        name = self.arguments[0]
+
+        slice_node = Slice()
+        slice_node["name"] = name
+
+        # adds parsed lines into the slice_node
+        for offset, line in enumerate(self.content):
+            if not line.strip():
+                continue
+            lineno = self.lineno + self.content_offset + offset
+            item = self.parse_item(line, lineno)
+            if isinstance(item, nodes.system_message):
+                return [item]
+            slice_node.append(item)
+
+        if not slice_node.children:
+            return [self.emit_error(f"slice '{name}' has no items")]
+
+        return [slice_node]
+
+    def parse_item(self, line: str, lineno: int) -> nodes.Node:
+        role_text, mark_slice, mark_domain, err = self.parse_line(line)
+        if err is not None:
+            return self.emit_error(err, lineno=lineno)
+
+        nodes_list, messages = self.state.inline_text(role_text, lineno)
+
+        if messages:
+            return self.emit_error(
+                f"slice item must be a :doc: role: {line!r}",
+                lineno=lineno,
+            )
+
+        # each line should contain one and only cross-reference and nothing else
+        xrefs = [n for n in nodes_list if isinstance(n, pending_xref)]
+        non_xrefs = [
+            n
+            for n in nodes_list
+            if not isinstance(n, pending_xref)
+            and not (isinstance(n, nodes.Text) and not str(n).strip())
+        ]
+
+        if len(xrefs) != 1 or non_xrefs:
+            return self.emit_error(
+                f"slice item must be a :doc: role: {line!r}",
+                lineno=lineno,
+            )
+
+        xref = xrefs[0]
+        if xref.get("refdomain") != "std" or xref.get("reftype") != "doc":
+            return self.emit_error(
+                f"slice item must be a :doc: role: {line!r}",
+                lineno=lineno,
+            )
+
+        # create a SliceItem from the line
+        item = SliceItem(rawsource=line)
+        if mark_slice:
+            item["mark_slice"] = True
+        if mark_domain:
+            item["mark_domain"] = True
+        item += xref
+        return item
+
+    def parse_line(self, line: str) -> tuple[str, bool, bool, str | None]:
+        """Parses a line into its components"""
+
+        mark_slice = mark_domain = False
+        text = line.rstrip()
+        parts = text.split()
+
+        while parts and parts[-1] in ("slice", "domain"):
+            marker = parts.pop()
+            if marker == "slice" and not mark_slice:
+                mark_slice = True
+            elif marker == "domain" and not mark_domain:
+                mark_domain = True
+            else:
+                parts.append(marker)  # duplicate, hand back to error path
+                break
+
+        if parts and parts[-1] in ("slice", "domain"):
+            return (
+                line,
+                False,
+                False,
+                f"unrecognised trailing token in slice item: {line!r}",
+            )
+
+        role_text = " ".join(parts)
+        return role_text, mark_slice, mark_domain, None
+
+    def emit_error(self, msg: str, lineno: int | None = None) -> nodes.system_message:
+        return self.state_machine.reporter.error(
+            msg,
+            nodes.literal_block(self.block_text, self.block_text),
+            line=lineno if lineno is not None else self.lineno,
+        )

sphinx_structured_toc/domain-list.css

@@ -0,0 +1,29 @@
+.domain-list > ul > li > ul {
+    display: inline;
+    margin: 0;
+    padding: 0;
+}
+
+.domain-list > ul > li > ul > li {
+    display: inline;
+    padding-left: 0.3em;
+    border-left: 1px solid currentColor;
+    margin-left: 0.3em;
+}
+
+.domain-list > ul > li > ul > li:first-child {
+    border-left: none;
+    margin-left: 0;
+    padding-left: 0;
+}
+
+.domain-list-label {font-weight: bold;}
+
+.domain-aria-target {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+}

sphinx_structured_toc/html.py

@@ -0,0 +1,190 @@
+"""HTML visitors for sphinx-structured-toc nodes (Phase 8).
+
+Renders the annotated doctree as semantic HTML:
+
+* ``Domain`` becomes ``<nav aria-labelledby="...">`` referencing either the
+  enclosing section's heading id (when the domain name is derived from a
+  section heading) or a visually-hidden ``<span id="..." class="domain-
+  aria-target">`` holding the name (when the domain name is overridden).
+  The nameless case (no argument and no enclosing section) is a fatal
+  build error, raised in ``transforms.py`` before rendering.
+* ``Slice`` becomes a ``<li>`` containing the slice label ``<span>`` plus
+  ``": "`` and a nested ``<ul>`` of items.
+* ``SliceItem`` becomes a ``<li>`` containing the resolved ``<a>``.
+
+For items marked ``slice`` and/or ``domain``, the ``<a>`` element
+receives ``id`` and ``aria-labelledby``. The ``<a>`` is emitted by
+Sphinx's own ``visit_reference``; this extension overrides that visitor
+(globally, via ``app.add_node(..., override=True)``) so that when the
+reference's parent is a ``SliceItem`` with the relevant flags set, the
+aria/id attributes are injected. All other references fall through to
+Sphinx's default behaviour.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from docutils import nodes
+
+
+def visit_domain(translator: Any, node: Any) -> None:
+    """Open the outer container for a Domain.
+
+    Emits ``<nav aria-labelledby="{section_id}">`` when the domain name
+    is derived from a section heading (not overridden), or
+    ``<nav aria-labelledby="{domain_span_id}">`` referencing a
+    visually-hidden ``<span id="{domain_span_id}" class="domain-aria-
+    target">{name}</span>`` when overridden. The nameless case (no
+    argument and no enclosing section) is a fatal build error raised in
+    ``transforms.py`` and never reaches the visitor.
+    """
+    overridden = bool(node.get("overridden", False))
+    section_id = node.get("section_id", "")
+    name = node.get("name", "")
+
+    if overridden:
+        # aria-labelledby on the nav points at a visually-hidden span
+        # inside, which is the single source of truth for the name and
+        # is also referenced by aria-labelledby on marked items.
+        span_id = node.get("domain_span_id", "")
+        translator.body.append(
+            f'<nav class="domain-list" aria-labelledby="{span_id}">'
+        )
+        # "domain-aria-target" visually hides the span while keeping it
+        # in the accessibility tree (styles in domain-list.css).
+        translator.body.append(
+            f'<span id="{span_id}" class="domain-aria-target">'
+            f'{translator.attval(name)}</span>'
+        )
+    else:
+        translator.body.append(
+            f'<nav class="domain-list" aria-labelledby="{section_id}">'
+        )
+
+    # One top-level <ul> for the slices.
+    translator.body.append("<ul>")
+
+
+def depart_domain(translator: Any, node: Any) -> None:
+    """Close the outer container for a Domain."""
+    translator.body.append("</ul>")
+    translator.body.append("</nav>")
+
+
+def visit_slice(translator: Any, node: Any) -> None:
+    """Open a slice as a <li> containing the label <span> and a nested <ul>.
+
+    The colon and trailing space sit in the parent <li>, after the
+    ``<span>``; not inside the span, not in CSS.
+    """
+    label_id = node.get("label_id", "")
+    name = node.get("name", "")
+    translator.body.append("<li>")
+    translator.body.append(
+        f'<span id="{label_id}" class="domain-list-label">'
+        f"{translator.attval(name)}</span>: "
+    )
+    translator.body.append("<ul>")
+
+
+def depart_slice(translator: Any, node: Any) -> None:
+    """Close a slice's nested <ul> and the slice <li>."""
+    translator.body.append("</ul></li>")
+
+
+def visit_slice_item(translator: Any, node: Any) -> None:
+    """Open a slice item as a <li>.
+
+    The ``<a>`` itself is emitted by Sphinx's ``visit_reference`` (which
+    we override to inject ``id``/``aria-labelledby`` when the parent
+    ``SliceItem`` is marked). Here we only open the wrapping ``<li>``.
+    """
+    translator.body.append("<li>")
+
+
+def depart_slice_item(translator: Any, node: Any) -> None:
+    """Close a slice item's <li>."""
+    translator.body.append("</li>")
+
+
+def make_reference_visitor(app: Any) -> tuple[Any, Any]:
+    """Build ``visit``/``depart`` overrides for ``docutils.nodes.reference``.
+
+    Returns ``(visit_reference, depart_reference)``. The visit function
+    delegates to Sphinx's original ``visit_reference`` for any reference
+    whose parent is not a marked ``SliceItem``. For marked ``SliceItem``
+    parents it injects ``id`` and ``aria-labelledby`` onto the ``<a>``
+    before delegating, so the rest of Sphinx's reference handling
+    (classes, href, secnumber, etc.) is preserved.
+
+    The override is registered globally via
+    ``app.add_node(docutils.nodes.reference, html=(...), override=True)``.
+    """
+    from sphinx.writers.html5 import HTML5Translator
+
+    from .nodes import SliceItem
+
+    original_visit = HTML5Translator.visit_reference
+    original_depart = getattr(HTML5Translator, "depart_reference", None)
+
+    def visit_reference(self: Any, node: nodes.reference) -> None:
+        parent = node.parent
+        if isinstance(parent, SliceItem) and (
+            parent.get("mark_slice") or parent.get("mark_domain")
+        ):
+            item_id = parent.get("item_id", "")
+            slice_node = parent.parent
+            domain_node = slice_node.parent if slice_node is not None else None
+            labelledby: list[str] = []
+            if item_id:
+                labelledby.append(item_id)
+            if parent.get("mark_slice") and slice_node is not None:
+                slice_label_id = slice_node.get("label_id", "")
+                if slice_label_id:
+                    labelledby.append(slice_label_id)
+            if parent.get("mark_domain") and domain_node is not None:
+                if domain_node.get("overridden", False):
+                    domain_id = domain_node.get("domain_span_id", "")
+                else:
+                    domain_id = domain_node.get("section_id", "")
+                if domain_id:
+                    labelledby.append(domain_id)
+            if item_id:
+                # ``starttag`` will emit the id from ``node['ids']``.
+                node.setdefault("ids", []).append(item_id)
+            # Delegate to Sphinx's visit_reference, then patch the
+            # opening tag it emitted to add aria-labelledby (Sphinx does
+            # not emit aria-* attributes on references by default).
+            mark = len(self.body)
+            original_visit(self, node)
+            if labelledby:
+                inject_aria_labelledby(self.body, mark, " ".join(labelledby))
+            return
+
+        original_visit(self, node)
+
+    def depart_reference(self: Any, node: nodes.reference) -> None:
+        if original_depart is not None:
+            original_depart(self, node)
+
+    return visit_reference, depart_reference
+
+
+def inject_aria_labelledby(body: list[str], since: int, value: str) -> None:
+    """Inject ``aria-labelledby="..."`` into the most recent ``<a ...>`` tag.
+
+    Sphinx's ``visit_reference`` appends the opening ``<a>`` tag as a
+    single string via ``self.starttag``. We locate that string in
+    ``body`` (searching backwards from the end, starting at ``since``)
+    and insert the attribute before the closing ``>``.
+    """
+    for i in range(len(body) - 1, since - 1, -1):
+        chunk = body[i]
+        if "<a " in chunk or chunk.startswith("<a"):
+            # Insert before the closing ">" of the opening tag.
+            idx = chunk.rfind(">")
+            if idx == -1:
+                continue
+            body[i] = chunk[:idx] + f' aria-labelledby="{value}"' + chunk[idx:]
+            return

sphinx_structured_toc/nodes.py

@@ -0,0 +1,13 @@
+from docutils import nodes
+
+
+class Domain(nodes.General, nodes.Element):
+    """Outer container for a ``.. domain::`` block."""
+
+
+class Slice(nodes.General, nodes.Element):
+    """A single named slice within a ``Domain``."""
+
+
+class SliceItem(nodes.General, nodes.TextElement):
+    """A single link entry within a ``Slice``."""

sphinx_structured_toc/transforms.py

@@ -0,0 +1,175 @@
+"""Post-transform resolution for the sphinx-structured-toc extension."""
+
+from __future__ import annotations
+
+from docutils import nodes
+from sphinx.util.logging import getLogger
+
+from .nodes import Domain, Slice, SliceItem
+
+_logger = getLogger(__name__)
+
+
+def nearest_section(node: nodes.Node) -> nodes.section | None:
+    """Return the nearest enclosing ``nodes.section`` for ``node``, or ``None``."""
+    parent = node.parent
+    while parent is not None:
+        if isinstance(parent, nodes.section):
+            return parent
+        parent = parent.parent
+    return None
+
+
+def section_title(section: nodes.section) -> str:
+    """Return the text of a section's first ``nodes.title`` child, or ``""``."""
+    title = section.next_node(nodes.title)
+    return title.astext() if title is not None else ""
+
+
+def section_id(section: nodes.section) -> str:
+    """Return the section's first id, or ``""`` when it has none."""
+    ids = section.get("ids", [])
+    return ids[0] if ids else ""
+
+
+def visible_text(item: SliceItem) -> str:
+    """Return the visible text of a SliceItem's resolved ``:doc:`` reference."""
+
+    from docutils import nodes as _nodes
+
+    for child in item.children:
+        if isinstance(child, _nodes.reference):
+            return child.astext()
+    return ""
+
+
+def accessible_name(item: SliceItem, slice_node: Slice, domain: Domain) -> str:
+    """Return the accessible name of a marked item."""
+
+    parts: list[str] = [visible_text(item)]
+    if item.get("mark_slice"):
+        parts.append(slice_node["name"])
+    if item.get("mark_domain"):
+        parts.append(domain["name"])
+    return " ".join(parts)
+
+
+def check_ambiguity(doctree) -> None:
+    """Warn at each occurrence of repeated visible text with identical accessible names."""
+
+    # Group items by visible text across the whole page, recording the
+    # accessible name and the slice/domain each came from so the
+    # same-slice special case can be detected.
+    occurrences: dict[str, list[tuple[SliceItem, Slice, Domain]]] = {}
+    for domain in doctree.findall(Domain):
+        if domain.get("suppress_warnings", False):
+            continue
+        for slice_node in domain.findall(Slice):
+            for item in slice_node.children:
+                if not isinstance(item, SliceItem):
+                    continue
+                text = visible_text(item)
+                if not text:
+                    continue
+                occurrences.setdefault(text, []).append((item, slice_node, domain))
+
+    for text, group in occurrences.items():
+        if len(group) < 2:
+            continue
+
+        # Same-slice special case: any two items in the same slice
+        # instance with the same visible text always warn.
+        for i, (item_i, slice_i, _dom_i) in enumerate(group):
+            for j, (item_j, slice_j, _dom_j) in enumerate(group):
+                if j <= i:
+                    continue
+                if slice_i is slice_j:
+                    _logger.warning(
+                        "ambiguous link text %r: repeated within slice %r",
+                        text,
+                        slice_i["name"],
+                    )
+                    continue
+                # Cross-slice: warn unless accessible names differ.
+                name_i = accessible_name(item_i, slice_i, _dom_i)
+                name_j = accessible_name(item_j, slice_j, _dom_j)
+                if name_i == name_j:
+                    _logger.warning(
+                        "ambiguous link text %r: identical accessible "
+                        "name %r across slices %r and %r",
+                        text,
+                        name_i,
+                        slice_i["name"],
+                        slice_j["name"],
+                    )
+
+
+def unique_id(base: str, used: set[str]) -> str:
+    """Return ``base`` if unused, else ``base-2``, ``base-3``, ... on clash."""
+
+    candidate = base
+    counter = 2
+    while candidate in used:
+        candidate = f"{base}-{counter}"
+        counter += 1
+    used.add(candidate)
+    return candidate
+
+
+def resolve_domains(_app, doctree, _docname) -> None:
+    """``doctree-resolved`` handler: fill in name/section_id and assign ids."""
+    used_ids: set[str] = set()
+
+    # Seed with ids already present on the page (section heading ids,
+    # etc.) so generated ids never collide with existing ones.
+    for node in doctree.findall(nodes.Element):
+        for existing in node.get("ids", []):
+            used_ids.add(existing)
+
+    for domain in doctree.findall(Domain):
+        section = nearest_section(domain)
+        overridden = domain.get("overridden", False)
+        if section is not None:
+            domain["section_id"] = section_id(section)
+            if not overridden:
+                domain["name"] = section_title(section)
+        else:
+            domain["section_id"] = ""
+            if not overridden:
+                # No name available from anywhere: an unlabelled landmark
+                # is worse for screen reader users than no landmark at all,
+                # so fail the build rather than degrading to a nameless
+                # container.
+                _logger.error(
+                    "domain directive requires an explicit name argument "
+                    "or an enclosing section heading to derive one from"
+                )
+                continue
+
+        section_slug = domain["section_id"]
+
+        if domain.get("overridden", False):
+            name_slug = nodes.make_id(domain["name"])
+            domain["domain_span_id"] = unique_id(f"{name_slug}-domain", used_ids)
+
+        for slice_node in domain.findall(Slice):
+            slice_slug = nodes.make_id(slice_node["name"])
+            if section_slug:
+                base = f"{section_slug}-{slice_slug}"
+            else:
+                base = slice_slug
+            slice_node["label_id"] = unique_id(base, used_ids)
+
+            for item in slice_node.children:
+                if not isinstance(item, SliceItem):
+                    continue
+                if not (item.get("mark_slice") or item.get("mark_domain")):
+                    continue
+                link_text = visible_text(item)
+                if not link_text:
+                    continue
+                link_slug = nodes.make_id(link_text)
+                base = f"{slice_node['label_id']}-{link_slug}"
+                item["item_id"] = unique_id(base, used_ids)
+
+    check_ambiguity(doctree)