prodockit 0.1.0__py3-none-any.whl

prodockit/__init__.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""prodockit: a family of extensions for Zensical (https://zensical.org/) -
+the pieces professional and academic documentation commonly needs that
+Zensical doesn't provide out of the box, each usable independently:
+
+- ``prodockit.headings`` - heading ids and hierarchical section numbers.
+- ``prodockit.refs`` - ``\\ref{id}`` section cross-references.
+- ``prodockit.citations`` - define a source once, cite it by key anywhere with
+  ``\\cite{id}``.
+- ``prodockit.glossary`` - define a term once, insert it by id anywhere with
+  ``\\gls{id}``.
+- ``prodockit.pdf`` - build a standalone PDF from your Zensical site via
+  Pandoc and WeasyPrint, the kind of downloadable, submittable document
+  professional/academic reports typically need alongside the website
+  itself. Run ``prodockit pdf`` from your project root - no Python required,
+  it reads the same ``zensical.toml`` your site already has.
+- ``prodockit.zensical_macros`` - Jinja variables/macros for Zensical's own
+  macros plugin: a site-wide word count, the git-detected repository URL,
+  chapter/appendix numbering that continues across pages, and reference/
+  acronym/glossary spacing that matches ``prodockit.pdf``'s own PDF output.
+
+``prodockit.headings``/``prodockit.refs``/``prodockit.citations``/``prodockit.glossary``
+are Python-Markdown extensions, in the spirit of pymdown-extensions - enable
+one in `zensical.toml` the same way as a built-in or pymdownx extension.
+Zensical's per-page rendering context is detected automatically where it's
+useful (see their own cross-page registry sharing). ``prodockit.pdf`` is a
+command-line tool instead (there's no ``markdown.extensions`` entry point
+for it - a PDF build pipeline isn't a Markdown syntax extension).
+``prodockit.zensical_macros`` is a plain ``define_env()`` module for Zensical's
+macros plugin's own ``modules`` config, not a Markdown extension either.
+
+See https://buckwem.github.io/prodockit-extensions/ for documentation.
+"""
+
+__version__ = "0.10.0"
+
+__all__ = ["__version__"]

prodockit/_zensical.py

@@ -0,0 +1,260 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""Internal helpers for Zensical-aware, cross-page state sharing.
+
+Not part of prodockit's public API - shared by prodockit.headings,
+prodockit.citations, and prodockit.glossary, all of which face the same problem:
+Zensical builds each page with its own fresh ``Markdown`` instance, so a
+plain per-instance default registry can never see another page's entries.
+``nav_pages``/``preseed_attr_from_nav`` (used by prodockit.citations and
+prodockit.glossary) additionally address pages being built in a single,
+one-shot pass: a forward reference to a page not yet built can't resolve
+without pre-scanning ahead of time.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Protocol, TypeVar
+
+from markdown import Markdown
+
+T = TypeVar("T")
+
+
+def page_source(md: Markdown) -> str | None:
+    """Returns the current page's path if running under Zensical's per-page
+    ``render()``, else None.
+
+    Zensical stashes a ``Page`` (with a stable, per-page path) on every
+    ``Markdown`` instance it builds, via its own ``ContextPreprocessor`` -
+    used as a best-effort default for ``source`` when the caller hasn't set
+    one explicitly, since without it every page would silently share the
+    same default source (``""``), each page wiping the previous one's
+    registry entries on every render. Returns None (falling back to
+    ordinary behaviour) under any other Python-Markdown tool, or if
+    Zensical isn't installed.
+    """
+    try:
+        from zensical.extensions.context import ContextPreprocessor
+    except ImportError:
+        return None
+    context = ContextPreprocessor.from_markdown(md)
+    if context is None or context.page is None:
+        return None
+    return context.page.path
+
+
+def share(md: Markdown, attr: str, value: T) -> T:
+    """Order-independent same-page sharing between two prodockit extensions
+    that both want the same piece of state (e.g. prodockit.headings and
+    prodockit.refs sharing an IdRegistry): whichever extension's
+    extendMarkdown() runs first claims `value` by stashing it on `md` under
+    `attr`; whichever runs second reuses what's already there - regardless
+    of which order the two extensions were listed in (Zensical's own
+    TOML-to-extension-list conversion doesn't preserve list order, so this
+    can't be assumed).
+    """
+    existing = getattr(md, attr, None)
+    if existing is not None:
+        return existing  # type: ignore[no-any-return]
+    setattr(md, attr, value)
+    return value
+
+
+def nav_pages() -> tuple[str, list[str]] | None:
+    """Returns (docs_dir, [nav markdown file paths]) from Zensical's own
+    already-parsed build configuration, if running under Zensical with that
+    configuration actually populated (i.e. mid-build - `zensical.config.get_config()`
+    returns an empty/absent config otherwise, e.g. under a plain script
+    import). Returns None in that case, or if Zensical isn't installed.
+
+    Used to pre-scan every page's raw text for something (currently
+    prodockit.citations' citation definitions) before any single page has
+    actually been converted - needed because Zensical's `render()` builds
+    one page a time, in one pass, so a page late in nav order (e.g. a
+    references page kept as an appendix) hasn't been touched yet at the
+    point an early page might already want to resolve something defined
+    there.
+    """
+    try:
+        from zensical.config import get_config
+    except ImportError:
+        return None
+    config = get_config()
+    if not config:
+        return None
+    docs_dir = config.get("docs_dir")
+    nav = config.get("nav")
+    if not docs_dir or not nav:
+        return None
+    return str(docs_dir), _flatten_nav(nav)
+
+
+def _flatten_nav(items: object) -> list[str]:
+    """Flattens Zensical's normalised nav structure (a list of
+    {"url": ..., "children": [...]} dicts, possibly nested) into a plain
+    list of markdown file paths, in nav order."""
+    paths: list[str] = []
+    if not isinstance(items, list):
+        return paths
+    for item in items:
+        if isinstance(item, dict):
+            url = item.get("url")
+            if url:
+                paths.append(url)
+            paths.extend(_flatten_nav(item.get("children")))
+        elif isinstance(item, list):
+            paths.extend(_flatten_nav(item))
+    return paths
+
+
+class _Preseedable(Protocol):
+    def preseed(self, source: str, id: str, text: str) -> None: ...
+
+
+_ATTR_RE = re.compile(r"\{:\s*([^}]+?)\s*\}")
+_ID_RE = re.compile(r"#([\w-]+)")
+_FENCE_RE = re.compile(
+    r"^[ \t]*```.*?^[ \t]*```[ \t]*$|^[ \t]*~~~.*?^[ \t]*~~~[ \t]*$",
+    re.MULTILINE | re.DOTALL,
+)
+
+
+def _strip_fences(text: str) -> str:
+    """Blanks out fenced code blocks before a raw-text regex scan, so a
+    documentation page showing a definition syntax as a *literal example*
+    inside a fenced code block isn't mistaken for a real definition by
+    preseed_attr_from_nav (which, unlike the real per-page treeprocessor,
+    scans raw text directly rather than the parsed, fence-aware
+    Python-Markdown tree)."""
+    return _FENCE_RE.sub("", text)
+
+
+def _front_matter_flag(text: str, key: str) -> bool:
+    """True if raw file text's YAML front matter sets ``key: true``. Used by
+    prescan_headings() to detect an appendix-flagged page ahead of that page
+    actually being converted."""
+    if not text.startswith("---"):
+        return False
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return False
+    return bool(
+        re.search(rf"^{re.escape(key)}:\s*true\s*$", parts[1], re.MULTILINE | re.IGNORECASE)
+    )
+
+
+def _count_top_level_headings(text: str) -> int:
+    """Counts top-level (single ``#``) ATX headings in raw markdown text,
+    skipping fenced code blocks, HTML comments, and headings tagged
+    ``{.unnumbered}`` - used by prescan_headings() to work out how many
+    numbered h1s appear on a page before any page has actually been
+    converted. Line-based rather than a single regex (unlike _strip_fences()
+    above) since it also needs to track HTML comments, not just fences, in
+    one pass."""
+    count = 0
+    in_fence = False
+    in_comment = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not in_comment and (stripped.startswith("```") or stripped.startswith("~~~")):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        if not in_comment and "<!--" in stripped:
+            in_comment = True
+        if in_comment:
+            if "-->" in stripped:
+                in_comment = False
+            continue
+        if re.match(r"^#\s+\S", line) and ".unnumbered" not in line:
+            count += 1
+    return count
+
+
+def prescan_headings(appendix_attr: str) -> tuple[dict[str, int], dict[str, str]] | None:
+    """Returns ``(start_counts, appendix_letters)``, both keyed by
+    nav-relative page path, by pre-scanning every page in the current
+    Zensical build's nav - the same "before any page has actually been
+    converted" pre-scan preseed_attr_from_nav does for citation/glossary
+    definitions, applied to heading counts instead.
+
+    ``start_counts[page]`` is how many numbered h1s appear on every earlier
+    nav page, for prodockit.headings' "continuous" numbering mode to seed this
+    page's own h1 counter with - so numbering continues seamlessly from one
+    page to the next instead of resetting per page. A page whose front
+    matter sets `appendix_attr` is skipped entirely for this count (it
+    doesn't consume a number from the sequence) and instead gets a
+    sequential letter in ``appendix_letters`` - "A" for the first such page
+    in nav order, "B" for the second, and so on.
+
+    Returns None outside a Zensical build (mirrors nav_pages()).
+    """
+    located = nav_pages()
+    if located is None:
+        return None
+    docs_dir, pages = located
+    start_counts: dict[str, int] = {}
+    appendix_letters: dict[str, str] = {}
+    running_total = 0
+    next_letter_index = 0
+    for rel_path in pages:
+        try:
+            text = (Path(docs_dir) / rel_path).read_text(encoding="utf-8")
+        except OSError:
+            continue
+        if _front_matter_flag(text, appendix_attr):
+            next_letter_index += 1
+            appendix_letters[rel_path] = chr(ord("A") + next_letter_index - 1)
+            continue
+        start_counts[rel_path] = running_total
+        running_total += _count_top_level_headings(text)
+    return start_counts, appendix_letters
+
+
+def preseed_attr_from_nav(registry: _Preseedable, attr_name: str) -> None:
+    """Pre-scans every page in the current Zensical build's nav for a
+    ``{: #id <attr_name>="..." }`` attr_list definition, provisionally
+    registering each one (via ``registry.preseed``) before any page has
+    actually been converted.
+
+    Fixes the classic "cited/referenced before defined" ordering problem: a
+    source is usually cited/referenced from an early chapter but defined on
+    a references/acronyms/glossary page kept at the end of nav, which -
+    without this - is a forward reference to a page `zensical build`'s
+    single, one-shot process hasn't rendered yet (unlike `zensical serve`'s
+    live-reload, which eventually rebuilds every page at least once). Reads
+    raw file text directly rather than waiting for Python-Markdown to parse
+    it - safe here because the id/value are already literal attr_list
+    attribute values, unlike e.g. prodockit.headings' section numbers, which
+    genuinely depend on running the real Python-Markdown pipeline to
+    compute. Skips fenced code blocks, so a documentation page showing this
+    exact attr_list syntax as a literal example doesn't get mistaken for a
+    real definition.
+
+    Used by prodockit.citations (`attr_name="data-cite-text"`) and
+    prodockit.glossary (`attr_name="data-term"`) - both need the identical
+    scan, differing only in which attribute they're looking for and which
+    registry they feed.
+    """
+    located = nav_pages()
+    if located is None:
+        return
+    docs_dir, pages = located
+    value_re = re.compile(attr_name + r'="([^"]*)"')
+    for rel_path in pages:
+        try:
+            text = (Path(docs_dir) / rel_path).read_text(encoding="utf-8")
+        except OSError:
+            continue
+        text = _strip_fences(text)
+        for attr_match in _ATTR_RE.finditer(text):
+            attrs = attr_match.group(1)
+            id_match = _ID_RE.search(attrs)
+            value_match = value_re.search(attrs)
+            if id_match and value_match:
+                registry.preseed(rel_path, id_match.group(1), value_match.group(1))

prodockit/citations.py

@@ -0,0 +1,207 @@
+# Copyright (c) 2026 Mark Buckwell and contributors
+# SPDX-License-Identifier: MIT
+
+"""prodockit.citations: define a citation source once, cite it by key anywhere.
+
+Mark a source's paragraph (or any block) with an id and a short display
+text via ``attr_list``:
+
+    Skoulikari, A. (2023) *Learning Git*. Sebastopol, CA: O'Reilly Media.
+    {: #skou2023 .reference data-cite-text="Skoulikari, 2023" }
+
+then cite it from anywhere in the build with ``\\cite{skou2023}``, which
+resolves to a linked, bracketed citation: ``[Skoulikari, 2023]``. Multiple
+keys in one citation (``\\cite{skou2023,chacon2014}``) render as
+``[Skoulikari, 2023; Chacon and Straub, 2014]``.
+
+Unlike prodockit.headings/prodockit.refs, defining and citing are bundled into one
+extension here rather than split in two: a definition is useless without a
+place to cite it, and a citation is meaningless without something defined
+to point at - there's no independently useful "just defining" half the way
+prodockit.headings' ids/numbers are useful even without prodockit.refs.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as etree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.inlinepatterns import InlineProcessor
+from markdown.treeprocessors import Treeprocessor
+
+from prodockit._zensical import page_source, preseed_attr_from_nav, share
+from prodockit.util import CitationRegistry, cross_page_href
+
+CITE_RE = r"\\cite\{([^}]+)\}"
+
+# Shared across every page of a single Zensical build - see prodockit._zensical
+# and CitationsExtension.extendMarkdown. Never touched unless Zensical's
+# per-page context is actually detected.
+_ZENSICAL_SHARED_REGISTRY = CitationRegistry()
+
+
+class CitationDefTreeprocessor(Treeprocessor):
+    """Registers every element carrying a ``data-cite-text`` attribute
+    (typically set via ``attr_list``, e.g. ``{: #skou2023 data-cite-text="Skoulikari, 2023" }``)
+    in a shared :class:`~prodockit.util.CitationRegistry`, keyed by the current
+    document's source name, then strips the attribute - it's internal
+    bookkeeping, not meant to leak into the rendered HTML.
+
+    Runs at a lower priority than 'attr_list' (registered at 8) so it always
+    sees the id/attribute attr_list assigned, rather than racing it.
+    """
+
+    def __init__(
+        self, md: Markdown, registry: CitationRegistry, source: str, strict: bool = True
+    ) -> None:
+        super().__init__(md)
+        self.registry = registry
+        self.source = source
+        self.strict = strict
+
+    def run(self, root: etree.Element) -> None:
+        self.registry.clear_source(self.source)
+        for el in root.iter():
+            text = el.get("data-cite-text")
+            if text is None:
+                continue
+            del el.attrib["data-cite-text"]
+            citation_id = el.get("id")
+            if not citation_id:
+                continue
+            self.registry.register(
+                source=self.source,
+                id=citation_id,
+                text=text,
+                strict=self.strict,
+            )
+
+
+class CiteInlineProcessor(InlineProcessor):
+    """Matches ``\\cite{id}`` or ``\\cite{id1,id2,...}`` and emits an
+    unresolved placeholder ``<span>`` carrying the raw, comma-separated keys
+    in a ``data-prodockit-cite`` attribute.
+
+    Registered at a low inline-pattern priority so it runs after 'backtick'
+    (190) and 'escape' (180) - meaning inline code spans are already stashed
+    out of reach by the time this pattern runs, so ``\\cite{...}`` shown as
+    literal example syntax survives untouched, the same protection fenced
+    code blocks get from being stashed even earlier, during preprocessing.
+    """
+
+    def handleMatch(  # type: ignore[override]
+        self, m: re.Match[str], data: str
+    ) -> tuple[etree.Element, int, int]:
+        el = etree.Element("span")
+        el.set("data-prodockit-cite", m.group(1))
+        return el, m.start(0), m.end(0)
+
+
+class CiteResolverTreeprocessor(Treeprocessor):
+    """Resolves the placeholder ``<span data-prodockit-cite="...">`` elements
+    left by :class:`CiteInlineProcessor` into a bracketed citation, once the
+    current document's own citation definitions have been registered.
+
+    Runs at a lower priority than 'prodockit-citations-def' so a citation can
+    reference a source defined further down the same document - or on a
+    page not yet built in a Zensical multi-page site, which instead falls
+    back to `unresolved` for that key, the same way prodockit.refs does.
+    """
+
+    def __init__(
+        self, md: Markdown, registry: CitationRegistry, source: str, unresolved: str = "?"
+    ) -> None:
+        super().__init__(md)
+        self.registry = registry
+        self.source = source
+        self.unresolved = unresolved
+
+    def run(self, root: etree.Element) -> None:
+        for el in root.iter("span"):
+            raw_keys = el.get("data-prodockit-cite")
+            if raw_keys is None:
+                continue
+            del el.attrib["data-prodockit-cite"]
+            el.set("class", "prodockit-cite")
+            keys = [key.strip() for key in raw_keys.split(",") if key.strip()]
+            el.text = "["
+            last = len(keys) - 1
+            for i, key in enumerate(keys):
+                record = self.registry.get(key)
+                a = etree.SubElement(el, "a")
+                if record is None:
+                    a.text = self.unresolved
+                    a.set("class", "prodockit-cite-unresolved")
+                else:
+                    a.text = record.text
+                    a.set("href", cross_page_href(record.source, self.source, key))
+                a.tail = "]" if i == last else "; "
+
+
+class CitationsExtension(Extension):
+    """Python-Markdown extension providing citation-key definitions and the
+    ``\\cite{id}`` syntax."""
+
+    def __init__(self, **kwargs: object) -> None:
+        # See prodockit.headings.HeadingsExtension for why this is popped
+        # rather than run through Extension's own config/setConfig
+        # machinery.
+        registry = kwargs.pop("registry", None)
+        self._registry_explicit = isinstance(registry, CitationRegistry)
+        self.registry: CitationRegistry = (
+            registry if isinstance(registry, CitationRegistry) else CitationRegistry()
+        )
+        self.config = {
+            "source": [
+                "",
+                "Identifier for the current document (e.g. its path), used "
+                "to scope this document's own citation definitions in the "
+                "registry.",
+            ],
+            "unresolved": [
+                "?",
+                "Text rendered for a \\cite{id} key that doesn't resolve to "
+                "a definition.",
+            ],
+        }
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        md.registerExtension(self)
+        source: str = self.getConfig("source")
+        registry = self.registry
+        strict = True
+        # Only kick in when the caller hasn't configured anything
+        # themselves - see HeadingsExtension.extendMarkdown for the same
+        # pattern and rationale.
+        if not self._registry_explicit and not source:
+            detected_source = page_source(md)
+            if detected_source is not None:
+                source = detected_source
+                registry = _ZENSICAL_SHARED_REGISTRY
+                strict = False
+                preseed_attr_from_nav(registry, "data-cite-text")
+        registry = share(md, "prodockit_citation_registry", registry)
+        self.registry = registry
+        unresolved: str = self.getConfig("unresolved")
+        md.treeprocessors.register(
+            CitationDefTreeprocessor(md, registry, source, strict=strict),
+            "prodockit-citations-def",
+            6,
+        )
+        md.inlinePatterns.register(
+            CiteInlineProcessor(CITE_RE, md),
+            "prodockit-cite",
+            44,
+        )
+        md.treeprocessors.register(
+            CiteResolverTreeprocessor(md, registry, source, unresolved),
+            "prodockit-cite-resolver",
+            1,
+        )
+
+
+def makeExtension(**kwargs: object) -> CitationsExtension:
+    return CitationsExtension(**kwargs)