texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/fragments/index/__init__.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from texsmith.core.fragments.base import BaseFragment, FragmentPiece
+
+
+@dataclass(frozen=True)
+class IndexConfig:
+    has_index: bool
+
+    @classmethod
+    def from_context(cls, context: Mapping[str, Any]) -> IndexConfig:
+        has_flag = context.get("has_index")
+        entries = context.get("index_terms")
+        return cls(has_index=bool(has_flag) or bool(entries))
+
+    def inject_into(self, context: dict[str, Any]) -> None:
+        context["ts_index_enabled"] = self.has_index
+
+
+class IndexFragment(BaseFragment[IndexConfig]):
+    name: ClassVar[str] = "ts-index"
+    description: ClassVar[str] = "Index helpers with backmatter insertion."
+    pieces: ClassVar[list[FragmentPiece]] = [
+        FragmentPiece(
+            template_path=Path(__file__).with_name("ts-index.jinja.sty"),
+            kind="package",
+            slot="extra_packages",
+        ),
+        FragmentPiece(
+            template_path=Path(__file__).with_name("ts-index-backmatter.jinja.tex"),
+            kind="inline",
+            slot="fragment_backmatter",
+        ),
+    ]
+    attributes: ClassVar[dict[str, Any]] = {}
+    config_cls: ClassVar[type[IndexConfig]] = IndexConfig
+    source: ClassVar[Path] = Path(__file__).with_name("ts-index.jinja.sty")
+    context_defaults: ClassVar[dict[str, Any]] = {"extra_packages": "", "fragment_backmatter": ""}
+
+    def build_config(
+        self, context: Mapping[str, Any], overrides: Mapping[str, Any] | None = None
+    ) -> IndexConfig:
+        _ = overrides
+        return self.config_cls.from_context(context)
+
+    def inject(
+        self,
+        config: IndexConfig,
+        context: dict[str, Any],
+        overrides: Mapping[str, Any] | None = None,
+    ) -> None:
+        _ = overrides
+        config.inject_into(context)
+
+    def should_render(self, config: IndexConfig) -> bool:
+        return config.has_index
+
+
+fragment = IndexFragment()
+
+__all__ = ["IndexConfig", "IndexFragment", "fragment"]

texsmith/fragments/index/fragment.toml

@@ -0,0 +1,3 @@
+name = "ts-index"
+description = "Index helpers with backmatter insertion."
+entrypoint = "texsmith.fragments.index:fragment"

texsmith/fragments/index/ts-index-backmatter.jinja.tex

@@ -0,0 +1,3 @@
+\BLOCK{ if index_entries or has_index }
+\printindex
+\BLOCK{ endif }

texsmith/fragments/index/ts-index.jinja.sty

@@ -0,0 +1,12 @@
+\ProvidesPackage{ts-index}[2025/11/21 TeXSmith index helpers (generated)]
+
+\BLOCK{ set resolved_index_engine = index_engine|default("makeindex")|lower }
+\BLOCK{ if resolved_index_engine in ["texindy", "pyxindy"] }
+\RequirePackage[xindy]{imakeidx}
+\BLOCK{ else }
+\RequirePackage{imakeidx}
+\BLOCK{ endif }
+
+\makeindex
+
+\endinput

texsmith/fragments/keystrokes/__init__.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from texsmith.core.fragments.base import BaseFragment, FragmentPiece
+
+
+@dataclass(frozen=True)
+class KeystrokesConfig:
+    uses_keystrokes: bool
+
+    @classmethod
+    def from_context(cls, context: Mapping[str, Any]) -> KeystrokesConfig:
+        return cls(uses_keystrokes=_detect_keystrokes(context))
+
+    def inject_into(self, context: dict[str, Any]) -> None:
+        context["ts_keystrokes_enabled"] = self.uses_keystrokes
+
+
+class KeystrokesFragment(BaseFragment[KeystrokesConfig]):
+    name: ClassVar[str] = "ts-keystrokes"
+    description: ClassVar[str] = "Keyboard shortcut rendering helpers loaded only when needed."
+    pieces: ClassVar[list[FragmentPiece]] = [
+        FragmentPiece(
+            template_path=Path(__file__).with_name("ts-keystrokes.jinja.sty"),
+            kind="package",
+            slot="extra_packages",
+        )
+    ]
+    attributes: ClassVar[dict[str, Any]] = {}
+    config_cls: ClassVar[type[KeystrokesConfig]] = KeystrokesConfig
+    source: ClassVar[Path] = Path(__file__).with_name("ts-keystrokes.jinja.sty")
+    context_defaults: ClassVar[dict[str, Any]] = {"extra_packages": ""}
+
+    def build_config(
+        self, context: Mapping[str, Any], overrides: Mapping[str, Any] | None = None
+    ) -> KeystrokesConfig:
+        _ = overrides
+        return self.config_cls.from_context(context)
+
+    def inject(
+        self,
+        config: KeystrokesConfig,
+        context: dict[str, Any],
+        overrides: Mapping[str, Any] | None = None,
+    ) -> None:
+        _ = overrides
+        config.inject_into(context)
+
+    def should_render(self, config: KeystrokesConfig) -> bool:
+        return config.uses_keystrokes
+
+
+def _detect_keystrokes(context: Mapping[str, Any]) -> bool:
+    tokens = ("\\keystroke{", "\\keystrokes{")
+    for value in context.values():
+        if not isinstance(value, str):
+            continue
+        if any(token in value for token in tokens):
+            return True
+    return False
+
+
+fragment = KeystrokesFragment()
+
+__all__ = ["KeystrokesConfig", "KeystrokesFragment", "fragment"]

texsmith/fragments/keystrokes/fragment.toml

@@ -0,0 +1,3 @@
+name = "ts-keystrokes"
+description = "Conditional keystroke helpers."
+entrypoint = "texsmith.fragments.keystrokes:fragment"

texsmith/fragments/keystrokes/ts-keystrokes.jinja.sty

@@ -0,0 +1,20 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{ts-keystrokes}[2025/11/21 TeXSmith keystroke helpers]
+
+\RequirePackage{tikz}
+\usetikzlibrary{shadows}
+
+\newcommand*\keystroke[1]{%
+  \tikz[baseline=(key.base)]%
+  \node[%
+    draw,
+    fill=gray!10,
+    drop shadow={shadow xshift=0.25ex,shadow yshift=-0.25ex,fill=black!70,opacity=0.75},
+    rectangle,
+    rounded corners=1.5pt,
+    inner ysep=0.1em,
+    inner xsep=0.5em,
+    line width=0.5pt,
+    font=\scriptsize\sffamily
+  ](key) {#1\strut};%
+}

texsmith/fragments/todolist/__init__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from texsmith.core.fragments.base import BaseFragment, FragmentPiece
+
+
+@dataclass(frozen=True)
+class TodolistConfig:
+    uses_todolist: bool
+
+    @classmethod
+    def from_context(cls, context: Mapping[str, Any]) -> TodolistConfig:
+        return cls(uses_todolist=_detect_todolist(context))
+
+    def inject_into(self, context: dict[str, Any]) -> None:
+        context["ts_todolist_enabled"] = self.uses_todolist
+
+
+class TodolistFragment(BaseFragment[TodolistConfig]):
+    name: ClassVar[str] = "ts-todolist"
+    description: ClassVar[str] = (
+        "Todolist helper commands loaded when checklist macros are present."
+    )
+    pieces: ClassVar[list[FragmentPiece]] = [
+        FragmentPiece(
+            template_path=Path(__file__).with_name("ts-todolist.jinja.sty"),
+            kind="package",
+            slot="extra_packages",
+        )
+    ]
+    attributes: ClassVar[dict[str, Any]] = {}
+    config_cls: ClassVar[type[TodolistConfig]] = TodolistConfig
+    source: ClassVar[Path] = Path(__file__).with_name("ts-todolist.jinja.sty")
+    context_defaults: ClassVar[dict[str, Any]] = {"extra_packages": ""}
+
+    def build_config(
+        self, context: Mapping[str, Any], overrides: Mapping[str, Any] | None = None
+    ) -> TodolistConfig:
+        _ = overrides
+        return self.config_cls.from_context(context)
+
+    def inject(
+        self,
+        config: TodolistConfig,
+        context: dict[str, Any],
+        overrides: Mapping[str, Any] | None = None,
+    ) -> None:
+        _ = overrides
+        config.inject_into(context)
+
+    def should_render(self, config: TodolistConfig) -> bool:
+        return config.uses_todolist
+
+
+def _detect_todolist(context: Mapping[str, Any]) -> bool:
+    tokens = ("\\done", "\\wontfix", "\\begin{todolist}", "\\todolist")
+    for value in context.values():
+        if not isinstance(value, str):
+            continue
+        if any(token in value for token in tokens):
+            return True
+    return False
+
+
+fragment = TodolistFragment()
+
+__all__ = ["TodolistConfig", "TodolistFragment", "fragment"]

texsmith/fragments/todolist/fragment.toml

@@ -0,0 +1,3 @@
+name = "ts-todolist"
+description = "Conditional todolist helpers."
+entrypoint = "texsmith.fragments.todolist:fragment"

texsmith/fragments/todolist/ts-todolist.jinja.sty

@@ -0,0 +1,21 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{ts-todolist}[2025/11/21 TeXSmith todolist helpers]
+
+\RequirePackage{enumitem}
+\RequirePackage{amssymb}
+\RequirePackage{pifont}
+
+\newlist{todolist}{itemize}{2}
+\setlist[todolist]{label=$\square$, leftmargin=*}
+
+\newcommand{\cmark}{\ding{51}}% check mark
+\newcommand{\xmark}{\ding{55}}% cross mark
+
+\newcommand{\done}{%
+  \rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}%
+  \hspace{-2.5pt}%
+}
+
+\newcommand{\wontfix}{%
+  \rlap{$\square$}{\large\hspace{1pt}\xmark}%
+}

texsmith/fragments/typesetting/__init__.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from texsmith.core.fragments.base import BaseFragment, FragmentPiece
+from texsmith.core.templates.manifest import TemplateAttributeSpec, TemplateError
+
+
+@dataclass(frozen=True)
+class TypesettingConfig:
+    indent_mode: str | None
+    parskip: str | None
+    leading_mode: str | None
+    leading_value: str | None
+    lineno_enabled: bool
+
+    @classmethod
+    def from_context(cls, context: Mapping[str, Any]) -> TypesettingConfig:
+        paragraph = context.get("typesetting_paragraph")
+        leading = context.get("typesetting_leading")
+        lineno = bool(context.get("typesetting_lineno"))
+
+        indent_mode, parskip = _normalise_paragraph(paragraph)
+        leading_mode, leading_value = _normalise_leading(leading)
+
+        return cls(
+            indent_mode=indent_mode,
+            parskip=parskip,
+            leading_mode=leading_mode,
+            leading_value=leading_value,
+            lineno_enabled=lineno,
+        )
+
+    def enabled(self) -> bool:
+        return (
+            any(
+                option is not None for option in (self.indent_mode, self.parskip, self.leading_mode)
+            )
+            or self.lineno_enabled
+        )
+
+    def inject_into(self, context: dict[str, Any]) -> None:
+        context["ts_typesetting_indent_mode"] = self.indent_mode
+        context["ts_typesetting_parskip"] = self.parskip
+        context["ts_typesetting_leading_mode"] = self.leading_mode
+        context["ts_typesetting_leading_value"] = self.leading_value
+        context["ts_typesetting_enable_lineno"] = self.lineno_enabled
+        context["ts_typesetting_enabled"] = self.enabled()
+
+
+class TypesettingFragment(BaseFragment[TypesettingConfig]):
+    name: ClassVar[str] = "ts-typesetting"
+    description: ClassVar[str] = "Paragraph spacing, line spacing, and line numbers controls."
+    pieces: ClassVar[list[FragmentPiece]] = [
+        FragmentPiece(
+            template_path=Path(__file__).with_name("ts-typesetting.tex.jinja"),
+            kind="inline",
+            slot="extra_packages",
+        )
+    ]
+    attributes: ClassVar[dict[str, TemplateAttributeSpec]] = {
+        "typesetting_paragraph": TemplateAttributeSpec(
+            default=None,
+            type="mapping",
+            sources=[
+                "typesetting.paragraph",
+                "paragraph",
+            ],
+        ),
+        "typesetting_leading": TemplateAttributeSpec(
+            default=None,
+            type="string",
+            allow_empty=True,
+            sources=[
+                "typesetting.leading",
+                "leading",
+            ],
+        ),
+        "typesetting_lineno": TemplateAttributeSpec(
+            default=None,
+            type="boolean",
+            sources=[
+                "typesetting.lineno",
+                "lineno",
+            ],
+        ),
+    }
+
+    config_cls: ClassVar[type[TypesettingConfig]] = TypesettingConfig
+    source: ClassVar[Path] = Path(__file__).with_name("ts-typesetting.tex.jinja")
+    context_defaults: ClassVar[dict[str, Any]] = {"extra_packages": ""}
+
+    def build_config(
+        self, context: Mapping[str, Any], overrides: Mapping[str, Any] | None = None
+    ) -> TypesettingConfig:
+        _ = overrides
+        return self.config_cls.from_context(context)
+
+    def inject(
+        self,
+        config: TypesettingConfig,
+        context: dict[str, Any],
+        overrides: Mapping[str, Any] | None = None,
+    ) -> None:
+        _ = overrides
+        config.inject_into(context)
+
+    def should_render(self, config: TypesettingConfig) -> bool:
+        return config.enabled()
+
+
+def _normalise_paragraph(payload: Any) -> tuple[str | None, str | None]:
+    indent_mode: str | None = None
+    spacing: str | None = None
+
+    if payload is None:
+        return (indent_mode, spacing)
+
+    if isinstance(payload, Mapping):
+        indent_mode = _normalise_indent(payload.get("indent"))
+        spacing = _normalise_spacing(payload.get("spacing"))
+        return (indent_mode, spacing)
+
+    indent_mode = _normalise_indent(payload)
+    return (indent_mode, spacing)
+
+
+def _normalise_indent(value: Any) -> str | None:
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        return "always" if value else "none"
+
+    if isinstance(value, (int, float)):
+        return "always" if value else "none"
+
+    if isinstance(value, str):
+        token = value.strip().lower()
+        if not token:
+            return None
+        if token == "auto":
+            return "auto"
+        if token in {"true", "yes", "on", "indent", "indented"}:
+            return "always"
+        if token in {"false", "no", "off", "none"}:
+            return "none"
+    raise TemplateError("paragraph.indent must be one of: true, false, auto.")
+
+
+def _normalise_spacing(value: Any) -> str | None:
+    if value is None:
+        return None
+
+    if isinstance(value, (int, float)):
+        formatted = _format_number(float(value))
+        return f"{formatted}pt"
+
+    if isinstance(value, str):
+        trimmed = value.strip()
+        return trimmed or None
+
+    raise TemplateError("paragraph.spacing must be a string or number.")
+
+
+def _normalise_leading(value: Any) -> tuple[str | None, str | None]:
+    if value is None:
+        return (None, None)
+
+    if isinstance(value, (int, float)):
+        factor = float(value)
+        if factor <= 0:
+            raise TemplateError("leading must be a positive value.")
+        return ("factor", _format_number(factor))
+
+    if isinstance(value, str):
+        trimmed = value.strip()
+        if not trimmed:
+            return (None, None)
+
+        token = trimmed.lower()
+        if token in {"single", "singlespace", "singlespacing"}:
+            return ("single", None)
+        if token in {"onehalf", "one-half", "onehalfspacing", "one half"}:
+            return ("onehalf", None)
+        if token in {"double", "doublespacing", "double-spacing"}:
+            return ("double", None)
+
+        try:
+            factor = float(trimmed)
+        except ValueError:
+            return ("length", trimmed)
+
+        if factor <= 0:
+            raise TemplateError("leading must be a positive value.")
+        return ("factor", _format_number(factor))
+
+    raise TemplateError(
+        "leading must be 'single', 'onehalf', 'double', a length, or a positive number."
+    )
+
+
+def _format_number(value: float) -> str:
+    rounded = f"{value:.3f}"
+    cleaned = rounded.rstrip("0").rstrip(".")
+    return cleaned or "0"
+
+
+fragment = TypesettingFragment()
+
+__all__ = ["TypesettingConfig", "TypesettingFragment", "fragment"]

texsmith/fragments/typesetting/fragment.toml

@@ -0,0 +1,3 @@
+name = "ts-typesetting"
+description = "Paragraph spacing, leading, and line numbering helpers."
+entrypoint = "texsmith.fragments.typesetting:fragment"

texsmith/fragments/typesetting/ts-typesetting.tex.jinja

@@ -0,0 +1,81 @@
+\BLOCK{ if ts_typesetting_enabled }
+% Typesetting controls (paragraphs, leading, lineno)
+\makeatletter
+\BLOCK{ if ts_typesetting_indent_mode }
+\BLOCK{ if ts_typesetting_indent_mode == "always" }
+\@afterindenttrue
+\BLOCK{ elif ts_typesetting_indent_mode == "auto" }
+\@afterindentfalse
+\BLOCK{ elif ts_typesetting_indent_mode == "none" }
+\setlength{\parindent}{0pt}
+\@afterindentfalse
+\BLOCK{ endif }
+\BLOCK{ endif }
+\makeatother
+
+\BLOCK{ if ts_typesetting_parskip }
+\setlength{\parskip}{\VAR{ts_typesetting_parskip}}
+\BLOCK{ endif }
+
+\BLOCK{ if ts_typesetting_leading_mode }
+\makeatletter
+\@ifclassloaded{memoir}{%
+  \providecommand{\tsTypesettingApplySpacing}[1]{%
+    \ifcsname Spacing\endcsname
+      \Spacing{##1}%
+    \else
+      \renewcommand{\baselinestretch}{##1}\selectfont
+    \fi
+  }%
+  \providecommand{\tsTypesettingSingle}{%
+    \ifcsname SingleSpacing\endcsname
+      \SingleSpacing
+    \else
+      \tsTypesettingApplySpacing{1}%
+    \fi
+  }%
+  \providecommand{\tsTypesettingOnehalf}{%
+    \ifcsname OnehalfSpacing\endcsname
+      \OnehalfSpacing
+    \else
+      \tsTypesettingApplySpacing{1.5}%
+    \fi
+  }%
+  \providecommand{\tsTypesettingDouble}{%
+    \ifcsname DoubleSpacing\endcsname
+      \DoubleSpacing
+    \else
+      \tsTypesettingApplySpacing{2}%
+    \fi
+  }%
+}{%
+  \@ifpackageloaded{setspace}{}{%
+    \RequirePackage{setspace}%
+  }%
+  \providecommand{\tsTypesettingApplySpacing}[1]{\setstretch{##1}}%
+  \providecommand{\tsTypesettingSingle}{\singlespacing}%
+  \providecommand{\tsTypesettingOnehalf}{\onehalfspacing}%
+  \providecommand{\tsTypesettingDouble}{\doublespacing}%
+}
+\makeatother
+
+\BLOCK{ if ts_typesetting_leading_mode == "single" }
+\tsTypesettingSingle
+\BLOCK{ elif ts_typesetting_leading_mode == "onehalf" }
+\tsTypesettingOnehalf
+\BLOCK{ elif ts_typesetting_leading_mode == "double" }
+\tsTypesettingDouble
+\BLOCK{ elif ts_typesetting_leading_mode == "factor" }
+\tsTypesettingApplySpacing{\VAR{ts_typesetting_leading_value}}
+\BLOCK{ elif ts_typesetting_leading_mode == "length" }
+\setlength{\baselineskip}{\VAR{ts_typesetting_leading_value}}
+\BLOCK{ endif }
+\BLOCK{ endif }
+
+\BLOCK{ if ts_typesetting_enable_lineno }
+\@ifpackageloaded{lineno}{}{%
+  \RequirePackage{lineno}%
+}
+\AtBeginDocument{\linenumbers}
+\BLOCK{ endif }
+\BLOCK{ endif }

texsmith/index.py

@@ -0,0 +1,26 @@
+"""Public API exposing TeXSmith's hashtag index extension."""
+
+from __future__ import annotations
+
+from .extensions.index import (
+    IndexEntry,
+    IndexRegistry,
+    TexsmithIndexExtension,
+    clear_registry,
+    get_registry,
+)
+from .extensions.index.markdown import makeExtension
+from .extensions.index.mkdocs_plugin import IndexPlugin
+from .extensions.index.renderer import register as register_renderer
+
+
+__all__ = [
+    "IndexEntry",
+    "IndexPlugin",
+    "IndexRegistry",
+    "TexsmithIndexExtension",
+    "clear_registry",
+    "get_registry",
+    "makeExtension",
+    "register_renderer",
+]

texsmith/plugins/__init__.py

@@ -0,0 +1,14 @@
+"""Compatibility layer exposing plugin integrations to documentation.
+
+TeXSmith consolidated its plugin utilities under
+``texsmith.adapters.plugins``.  mkdocstrings still references the historical
+``texsmith.plugins`` namespace, so we re-export the maintained modules here to
+keep the public import path available.
+"""
+
+from __future__ import annotations
+
+from texsmith.adapters.plugins import material, snippet
+
+
+__all__ = ["material", "snippet"]

texsmith/progressbar.py

@@ -0,0 +1,8 @@
+"""Public entry points for the progress bar Markdown extension."""
+
+from __future__ import annotations
+
+from .extensions.progressbar import ProgressBarExtension, makeExtension, register_renderer
+
+
+__all__ = ["ProgressBarExtension", "makeExtension", "register_renderer"]

texsmith/quotes.py

@@ -0,0 +1,40 @@
+"""Markdown extension converting straight double quotes into semantic ``<q>`` tags."""
+
+from __future__ import annotations
+
+from re import Match
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Extension, Markdown
+from markdown.inlinepatterns import InlineProcessor
+from markdown.util import AtomicString
+
+
+class _QuoteInlineProcessor(InlineProcessor):
+    """Wrap straight double quotes in ``<q>`` elements."""
+
+    def handleMatch(  # type: ignore[override]  # noqa: N802
+        self,
+        match: Match[str],
+        data: str,
+    ) -> tuple[ElementTree.Element, int, int]:
+        text = match.group(1)
+        element = ElementTree.Element("q")
+        element.text = AtomicString(text)
+        return element, match.start(0), match.end(0)
+
+
+class TexsmithQuotesExtension(Extension):
+    """Register the quote inline processor."""
+
+    def extendMarkdown(self, md: Markdown) -> None:  # type: ignore[override]  # noqa: N802
+        pattern = r'(?<!\\)"([^"\n]+?)"'
+        processor = _QuoteInlineProcessor(pattern, md)
+        md.inlinePatterns.register(processor, "texsmith_quotes", 65)
+
+
+def makeExtension(**kwargs: object) -> TexsmithQuotesExtension:  # noqa: N802
+    return TexsmithQuotesExtension(**kwargs)
+
+
+__all__ = ["TexsmithQuotesExtension", "makeExtension"]