amethyst-cli 0.1.0__py3-none-any.whl

amethyst/render/furniture.py

@@ -0,0 +1,112 @@
+"""What goes on a page besides the document: contents, running head, cover.
+
+The two pipelines build this furniture in completely different ways — one in
+CSS paged media, the other in Word sections and field codes — but they must
+agree on *what* it says, or the same source comes out as two documents. The
+decisions that both have to make identically are made once, here, and nowhere
+else: which headings the contents lists, which heading level the running head
+tracks, and what the cover has on it.
+
+Nothing in this module knows about HTML or OOXML. It reads a parsed document
+and returns the answers.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from amethyst.document import Document, Heading
+
+#: What a table of contents is called. Not read from the document, because it
+#: is not in the document: it is furniture the renderer adds, and both formats
+#: have to add it under the same name.
+CONTENTS_HEADING = "Contents"
+
+#: The heading levels a contents can list at all. ``--toc-depth`` cuts into
+#: this; it cannot go past it, because ``h6`` is the last heading there is.
+MAX_TOC_DEPTH = 6
+
+
+@dataclass(frozen=True)
+class Cover:
+    """What a title page has on it, once the empty lines are taken out.
+
+    A cover is worth making only if it has a title. Everything else is
+    optional and simply absent when the frontmatter did not declare it.
+    """
+
+    title: str
+    subtitle: str | None = None
+    author: str | None = None
+    date: str | None = None
+
+
+def contents(document: Document, depth: int) -> list[Heading]:
+    """The headings a table of contents lists, in document order.
+
+    Deeper headings are dropped rather than flattened: a contents that lists
+    every ``h6`` in a long document is a second document, not a way into the
+    first.
+    """
+    return [item for item in document.headings if item.level <= depth]
+
+
+def section_level(document: Document) -> int | None:
+    """Which heading level the running head should name, if any.
+
+    A running head is useful when it changes — it tells a reader which part of
+    the document the page in their hand belongs to. So it tracks the shallowest
+    level that occurs more than once, which for the ordinary shape of a
+    Markdown file (one ``h1`` naming the document, ``h2`` sections under it)
+    is the ``h2``.
+
+    ``None`` when no level repeats: there is nothing to track, and a head that
+    names the one heading in the document is just the title written twice.
+    """
+    counts = Counter(item.level for item in document.headings)
+    for level in sorted(counts):
+        if counts[level] > 1:
+            return level
+    return None
+
+
+def cover(document: Document) -> Cover | None:
+    """The title page's content, or ``None`` if there is not enough for one.
+
+    Without a title there is no cover worth printing — a page carrying nothing
+    but an author's name is a blank page with a mistake on it — so this
+    returns nothing and the caller says so rather than emitting one.
+    """
+    title = document.title
+    if not title:
+        return None
+    return Cover(
+        title=title,
+        subtitle=document.subtitle,
+        author=document.author,
+        date=document.date,
+    )
+
+
+def outline_depth(headings: Sequence[Heading], depth: int) -> int:
+    """The deepest level actually present in a contents, for Word's ``TOC``.
+
+    Word's field takes a range of heading levels rather than a list, and a
+    range reaching past the deepest heading in the document is not wrong, only
+    untidy. One is the floor: ``TOC \\o "1-0"`` is not a range.
+    """
+    present = [item.level for item in headings if item.level <= depth]
+    return max(present, default=1)
+
+
+__all__ = [
+    "CONTENTS_HEADING",
+    "MAX_TOC_DEPTH",
+    "Cover",
+    "contents",
+    "cover",
+    "outline_depth",
+    "section_level",
+]

amethyst/render/highlight.py

@@ -0,0 +1,315 @@
+"""Syntax highlighting, compiled the same two ways a theme is.
+
+Pygments knows how to colour code and how to write the HTML for it. What it
+does not know is that this project has two pipelines which must agree, so what
+comes out of here is not Pygments' stylesheet but a small model of it: a
+colour, a weight and a slope per token class. The PDF path turns that into CSS
+rules and the Word path turns it into run formatting, from the same lookup, for
+exactly the reason :mod:`amethyst.theme` compiles two ways rather than one.
+
+Pygments' own ``get_style_defs`` is deliberately not used. It writes rules for
+line numbering that nothing here emits, and a ``pre { line-height: 125% }``
+that would quietly override the stylesheet's own leading — a highlighting style
+is meant to colour the code, not to re-typeset it.
+
+Two decisions are worth knowing about:
+
+A **light style keeps the theme's background.** Code then sits on the same fill
+as the inline code and the table headings around it, which is what makes a
+highlighted block still look like part of the document. A **dark style brings
+its own**, because it has to: its colours are chosen against a dark ground and
+are unreadable on a light one.
+
+**Nothing is guessed.** A fence with no language, or with one Pygments does not
+recognise, is set plain rather than passed to a guesser. Guessing is slow, and
+when it is wrong it is wrong in colour. Under a dark style such a block is
+still a dark panel, in both formats — a light box beside a dark one, a
+paragraph apart, is worse than an uncoloured one.
+
+Inline code is never highlighted: three words between backticks name no
+language, and there is nothing to lex. It keeps the theme's own fill even when
+the blocks around it are dark, because it belongs to the sentence it sits in
+rather than to a panel.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pygments import highlight as pygments_highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexer import Lexer
+from pygments.lexers import get_lexer_by_name
+from pygments.style import Style
+from pygments.styles import get_all_styles, get_style_by_name
+from pygments.token import STANDARD_TYPES, Token, _TokenType
+from pygments.util import ClassNotFound
+
+from amethyst.errors import UsageError
+from amethyst.render.base import DEFAULT_HIGHLIGHT_STYLE, Warn, discard
+
+#: What to pass to turn highlighting off. Not a Pygments style name — the point
+#: is to have a spelling for "leave the code alone", and code set in the mono
+#: face with no colour at all is a legitimate way to want a document to look.
+NO_HIGHLIGHTING = "none"
+
+#: Below this relative luminance a background counts as dark, and the style is
+#: taken to have been designed against its own ground rather than the page's.
+DARK_BELOW = 0.4
+
+#: The plain-text colour for a dark style that names none, which no shipped
+#: style does — a legible off-white rather than a guess at the style's intent.
+FALLBACK_FOREGROUND = "#f8f8f2"
+
+
+@dataclass(frozen=True)
+class Span:
+    """One run of code that is all one colour."""
+
+    text: str
+    color: str | None = None
+    bold: bool = False
+    italic: bool = False
+
+    @property
+    def plain(self) -> bool:
+        """Whether this span asks for nothing the surrounding style lacks."""
+        return self.color is None and not self.bold and not self.italic
+
+
+class Highlighter:
+    """One highlighting style, ready for either pipeline.
+
+    Built per render rather than cached, because it remembers which unknown
+    languages it has already complained about: a document that fences twenty
+    blocks as ```pseudocode`` should say so once, not twenty times.
+    """
+
+    def __init__(self, style: str = DEFAULT_HIGHLIGHT_STYLE, *, warn: Warn = discard):
+        self.name = resolve_highlight_style(style)
+        self._warn = warn
+        self._style: type[Style] | None = (
+            None if self.name == NO_HIGHLIGHTING else get_style_by_name(self.name)
+        )
+        self._unknown: set[str] = set()
+
+    @property
+    def enabled(self) -> bool:
+        """Whether this highlighter colours anything at all."""
+        return self._style is not None
+
+    @property
+    def background(self) -> str | None:
+        """The ground this style needs, or ``None`` to keep the theme's fill.
+
+        Only a dark style answers with a colour. See the module docstring: a
+        light style is an ornament on the page's own background, and a dark one
+        is a panel that brings its own.
+        """
+        if self._style is None:
+            return None
+        declared = _hex(self._style.background_color)
+        if declared is None or _luminance(declared) >= DARK_BELOW:
+            return None
+        return declared
+
+    @property
+    def foreground(self) -> str | None:
+        """The plain-text colour that goes with :attr:`background`."""
+        if self.background is None:
+            return None
+        assert self._style is not None
+        declared = self._format(Token.Text).color
+        return declared or FALLBACK_FOREGROUND
+
+    def html(self, code: str, language: str) -> str | None:
+        """The code as coloured ``<span>``s, or ``None`` to set it plain.
+
+        No wrapper: markdown-it puts the result inside the ``<pre><code>`` it
+        would have written anyway, so the stylesheet's idea of what a code
+        block is stays in one place.
+        """
+        lexer = self._lexer(language)
+        if lexer is None:
+            return None
+        formatter = HtmlFormatter(nowrap=True, style=self.name)
+        return pygments_highlight(code, lexer, formatter).rstrip("\n")
+
+    def spans(self, code: str, language: str) -> list[Span] | None:
+        """The code as coloured runs, or ``None`` to set it plain.
+
+        The Word side of :meth:`html`. Trailing newlines are dropped here
+        rather than by the caller: every lexer appends one, and in Word a
+        trailing newline is a visible empty line inside the shaded box.
+        """
+        lexer = self._lexer(language)
+        if lexer is None:
+            return None
+        found: list[Span] = []
+        for token, text in lexer.get_tokens(code):
+            style = self._format(token)
+            span = Span(
+                text=text,
+                color=style.color or self.foreground,
+                bold=style.bold,
+                italic=style.italic,
+            )
+            # A lexer emits a token per punctuation mark, and Word stores a run
+            # per span; merging the ones that are formatted alike takes a
+            # fenced block from hundreds of runs to a handful.
+            if found and _alike(found[-1], span):
+                found[-1] = Span(
+                    text=found[-1].text + span.text,
+                    color=span.color,
+                    bold=span.bold,
+                    italic=span.italic,
+                )
+            else:
+                found.append(span)
+        return _without_trailing_newline(found)
+
+    def css(self) -> str:
+        """The style as CSS rules, scoped to the code block they colour.
+
+        Rules are emitted shallowest token type first. They all have the same
+        specificity, so where Pygments gives a span more than one class it is
+        the later rule — the more specific token — that has to win.
+        """
+        if self._style is None:
+            return ""
+        lines = [f"/* highlighting: {self.name} */"]
+        background = self.background
+        if background is not None:
+            lines.append(
+                f"pre {{ background: {background}; color: {self.foreground}; "
+                f"border-color: {background}; }}"
+            )
+        for token, css_class in sorted(
+            STANDARD_TYPES.items(), key=lambda item: len(item[0])
+        ):
+            if not css_class:
+                continue
+            declarations = _declarations(self._format(token))
+            if declarations:
+                lines.append(f"pre .{css_class} {{ {declarations} }}")
+        return "\n".join([*lines, ""])
+
+    def _lexer(self, language: str) -> Lexer | None:
+        """The lexer for a fence's language, warning once when there is none."""
+        if self._style is None or not language:
+            return None
+        try:
+            return get_lexer_by_name(language)
+        except ClassNotFound:
+            if language not in self._unknown:
+                self._unknown.add(language)
+                self._warn(
+                    f"no syntax highlighting for {language!r}; that code is set plain."
+                )
+            return None
+
+    def _format(self, token: _TokenType) -> Span:
+        """How this style sets one token type, with inheritance resolved."""
+        assert self._style is not None
+        declared = self._style.style_for_token(token)
+        return Span(
+            text="",
+            color=_hex(declared["color"]),
+            bold=declared["bold"],
+            italic=declared["italic"],
+        )
+
+
+def resolve_highlight_style(name: str) -> str:
+    """Check that a highlighting style exists, returning it as given.
+
+    A name that is not a style is a mistyped invocation rather than a broken
+    document, so it exits 2 like an unknown theme does — and the hint lists
+    every style, because there is no other way to find out what they are
+    called.
+    """
+    if name == NO_HIGHLIGHTING:
+        return name
+    try:
+        get_style_by_name(name)
+    except ClassNotFound:
+        raise UsageError(
+            f"Unknown highlighting style {name!r}.",
+            hint=f"Styles: {', '.join(highlight_styles())}.",
+        ) from None
+    return name
+
+
+def highlight_styles() -> tuple[str, ...]:
+    """Every style that can be named, sorted, with ``none`` among them."""
+    return tuple(sorted([*get_all_styles(), NO_HIGHLIGHTING]))
+
+
+def _declarations(span: Span) -> str:
+    """One token class's formatting, as the body of a CSS rule."""
+    parts = []
+    if span.color is not None:
+        parts.append(f"color: {span.color};")
+    if span.bold:
+        parts.append("font-weight: 600;")
+    if span.italic:
+        parts.append("font-style: italic;")
+    return " ".join(parts)
+
+
+def _alike(one: Span, other: Span) -> bool:
+    """Whether two spans are formatted identically, text aside."""
+    return (one.color, one.bold, one.italic) == (other.color, other.bold, other.italic)
+
+
+def _without_trailing_newline(spans: list[Span]) -> list[Span]:
+    """Drop the newline every lexer adds, and any the author left behind."""
+    while spans:
+        trimmed = spans[-1].text.rstrip("\n")
+        if trimmed:
+            spans[-1] = Span(
+                text=trimmed,
+                color=spans[-1].color,
+                bold=spans[-1].bold,
+                italic=spans[-1].italic,
+            )
+            break
+        spans.pop()
+    return spans
+
+
+def _hex(color: str | None) -> str | None:
+    """A Pygments colour as CSS hex. It stores them without the ``#``.
+
+    A style that declares no colour for a token gives ``None``, and one that
+    declares no background gives ``""`` — both mean "say nothing here".
+    """
+    if not color:
+        return None
+    return color if color.startswith("#") else f"#{color}"
+
+
+def _luminance(color: str) -> float:
+    """Relative luminance of a hex colour, 0 for black and 1 for white.
+
+    The sRGB coefficients, without the gamma expansion a contrast ratio would
+    need: the only question being asked is "is this a dark panel or a light
+    page", and that answer does not change between the two.
+    """
+    digits = color.lstrip("#")
+    if len(digits) == 3:
+        digits = "".join(digit * 2 for digit in digits)
+    if len(digits) != 6:
+        return 1.0
+    red, green, blue = (int(digits[at : at + 2], 16) / 255 for at in (0, 2, 4))
+    return 0.2126 * red + 0.7152 * green + 0.0722 * blue
+
+
+__all__ = [
+    "DEFAULT_HIGHLIGHT_STYLE",
+    "NO_HIGHLIGHTING",
+    "Highlighter",
+    "Span",
+    "highlight_styles",
+    "resolve_highlight_style",
+]

amethyst/render/html.py

@@ -0,0 +1,266 @@
+"""Tokens to one standalone HTML document — the PDF pipeline's first half.
+
+Standalone on purpose. Everything the page needs is inlined, so the result can
+be written out and opened in a browser, which is by far the fastest way to tell
+a CSS mistake apart from a WeasyPrint limitation. It is also what an eventual
+HTML output would emit, which is why this is its own module rather than a
+private helper inside the PDF renderer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from html import escape
+from pathlib import Path
+from typing import Any, cast
+
+from markdown_it.renderer import RendererHTML
+from markdown_it.token import Token
+from markdown_it.utils import EnvType, OptionsDict
+
+from amethyst.document import Document
+from amethyst.errors import RenderError
+from amethyst.parse import build_parser
+from amethyst.parse.markdown import Highlight
+from amethyst.render.base import RenderOptions
+from amethyst.render.furniture import (
+    CONTENTS_HEADING,
+    contents,
+    cover,
+    section_level,
+)
+from amethyst.render.highlight import Highlighter
+from amethyst.theme import base_css
+from amethyst.theme.to_css import page_css, root_css
+
+#: Shown in the PDF's title bar when the document declares nothing better.
+FALLBACK_TITLE = "Untitled"
+
+
+def render_html(document: Document, options: RenderOptions) -> str:
+    """Render the document as one self-contained HTML page."""
+    # One highlighter for the whole page: it colours the code and it writes
+    # the rules that colour it, and those two have to be the same style.
+    highlighter = Highlighter(options.highlight_style, warn=options.warn)
+    sheets = stylesheets(document, options, highlighter)
+    return "\n".join(
+        [
+            "<!DOCTYPE html>",
+            '<html><head><meta charset="utf-8">',
+            f"<title>{escape(document.title or FALLBACK_TITLE)}</title>",
+            *meta_tags(document),
+            *(f"<style>\n{sheet}</style>" for sheet in sheets),
+            "</head>",
+            "<body>",
+            *front_matter(document, options),
+            render_body(document, highlighter),
+            "</body></html>",
+            "",
+        ]
+    )
+
+
+def meta_tags(document: Document) -> list[str]:
+    """The frontmatter, as the tags WeasyPrint turns into PDF metadata.
+
+    The same four fields the Word renderer writes into its core properties, so
+    that a reader looking at the document's information pane sees the same
+    thing whichever format they were sent. The date is written only when it is
+    a real one: ``dcterms.created`` is a timestamp, and a document dated
+    "Spring 2026" has a date for its title page and none for its metadata.
+    """
+    declared = [
+        ("author", document.author),
+        ("description", document.subtitle),
+        ("keywords", document.keywords),
+        ("dcterms.created", document.created.isoformat() if document.created else None),
+    ]
+    return [
+        f'<meta name="{name}" content="{escape(value, quote=True)}">'
+        for name, value in declared
+        if value
+    ]
+
+
+def front_matter(document: Document, options: RenderOptions) -> list[str]:
+    """The cover and the contents, in the order they are read."""
+    pages = []
+    if options.title_page:
+        pages += title_page_html(document, options)
+    if options.toc:
+        pages += contents_html(document, options)
+    return pages
+
+
+def title_page_html(document: Document, options: RenderOptions) -> list[str]:
+    """A cover built from the frontmatter, or nothing when there is no title."""
+    page = cover(document)
+    if page is None:
+        options.warn(
+            "--title-page needs a title; the document declares none, so no "
+            "title page was made."
+        )
+        return []
+    lines = ['<section class="title-page">']
+    for css_class, value in (
+        ("doc-title", page.title),
+        ("doc-subtitle", page.subtitle),
+        ("doc-author", page.author),
+        ("doc-date", page.date),
+    ):
+        if value:
+            lines.append(f'<p class="{css_class}">{escape(value)}</p>')
+    lines.append("</section>")
+    return lines
+
+
+def contents_html(document: Document, options: RenderOptions) -> list[str]:
+    """The table of contents, with the page numbers left for the PDF stage.
+
+    Every entry is written as a link, and the dots and the page number are
+    added by the stylesheet through ``target-counter`` — which only resolves
+    once the document has been laid out, so there is nothing to count here.
+    """
+    entries = contents(document, options.toc_depth)
+    if not entries:
+        options.warn(
+            "--toc needs headings; the document has none, so no contents was made."
+        )
+        return []
+    lines = [
+        '<nav class="contents">',
+        f'<h1 class="toc-heading">{CONTENTS_HEADING}</h1>',
+        "<ol>",
+    ]
+    for entry in entries:
+        label = escape(entry.text)
+        # An entry with no anchor cannot be linked, and so cannot carry a page
+        # number either — target-counter has nothing to resolve. Listing it
+        # unlinked beats dropping a heading out of the contents silently.
+        body = (
+            f'<a href="#{escape(entry.anchor, quote=True)}">{label}</a>'
+            if entry.anchor
+            else label
+        )
+        lines.append(f'<li class="toc-{entry.level}">{body}</li>')
+    lines += ["</ol>", "</nav>"]
+    return lines
+
+
+def render_body(document: Document, highlighter: Highlighter | None = None) -> str:
+    """Render just the token stream, with no page around it.
+
+    The parser is rebuilt rather than kept on the document because its options
+    — ``xhtmlOut``, the ``language-`` class prefix, the highlighter — are part
+    of how the tokens are meant to be written out, and they belong with the one
+    function that declares them.
+    """
+    md = build_parser(_fence_highlighter(highlighter))
+    # The parser's renderer is the HTML one, which the protocol the attribute
+    # is typed as does not say; the rules table is on the concrete class.
+    renderer = cast(RendererHTML, md.renderer)
+    # markdown-it types its rules table as holding bound methods, which a
+    # replacement rule is not and never was; the table itself takes any
+    # callable of the right shape.
+    rules: dict[str, Any] = renderer.rules
+    rules["ordered_list_open"] = _ordered_list_rule(renderer)
+    # The environment the frontmatter and footnote plugins filled during
+    # parsing is not needed to render: the only thing the render rules read
+    # from it is an optional id prefix for footnote anchors, which a
+    # single-document pipeline has no use for.
+    return renderer.render(document.tokens, md.options, {}).rstrip("\n")
+
+
+def _fence_highlighter(highlighter: Highlighter | None) -> Highlight | None:
+    """Adapt a highlighter to the three arguments markdown-it calls it with.
+
+    The third — whatever else was written on the fence line — is ignored:
+    markdown-it passes it along for the benefit of highlighters that take
+    options there, and nothing in this project reads one.
+    """
+    if highlighter is None or not highlighter.enabled:
+        return None
+
+    def highlight(code: str, language: str, _attrs: str) -> str | None:
+        return highlighter.html(code, language)
+
+    return highlight
+
+
+def _ordered_list_rule(renderer: RendererHTML) -> Callable[..., str]:
+    """Make a list start where the author said, rather than always at one.
+
+    ``4. four`` opens a list numbered from four, and markdown-it writes that
+    out as ``<ol start="4">`` — which WeasyPrint 69 does not read. Verified
+    against WeasyPrint on its own, with none of Amethyst's CSS loaded, so it
+    is the renderer and not the stylesheet. Setting the list-item counter
+    directly does work, and is what this adds.
+
+    The attribute is put on for the length of one call and taken off again:
+    the token stream belongs to the document, which the Word renderer walks
+    afterwards and has no use for a CSS declaration.
+    """
+
+    def ordered_list_open(
+        tokens: list[Token],
+        index: int,
+        options: OptionsDict,
+        env: EnvType,
+    ) -> str:
+        token = tokens[index]
+        start = token.attrGet("start")
+        if start is None:
+            rendered: str = renderer.renderToken(tokens, index, options, env)
+            return rendered
+        token.attrSet("style", f"counter-reset: list-item {int(start) - 1}")
+        try:
+            rendered = renderer.renderToken(tokens, index, options, env)
+        finally:
+            token.attrs.pop("style", None)
+        return rendered
+
+    return ordered_list_open
+
+
+def stylesheets(
+    document: Document,
+    options: RenderOptions,
+    highlighter: Highlighter | None = None,
+) -> list[str]:
+    """The stylesheets to inline, in cascade order — last one wins.
+
+    The theme goes after the structural sheet rather than before it: both
+    declare ``:root``, both at the same specificity, so the one that wins is
+    simply the one that comes second. The highlighting comes after the theme
+    for the same reason: a dark style has to be able to take the code block's
+    background off the theme, and it says so with a rule of equal weight.
+    """
+    if highlighter is None:
+        highlighter = Highlighter(options.highlight_style, warn=options.warn)
+    sheets = [
+        base_css(),
+        root_css(options.theme),
+        highlighter.css(),
+        page_css(
+            options.theme,
+            page_numbers=options.page_numbers,
+            running_title=document.title,
+            running_section=section_level(document),
+            front_matter=options.title_page or options.toc,
+            title_page=options.title_page,
+        ),
+    ]
+    if options.extra_css is not None:
+        sheets.append(read_css(options.extra_css))
+    return sheets
+
+
+def read_css(path: Path) -> str:
+    """Read a user's extra stylesheet, reporting a failure as one clear line."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        detail = getattr(exc, "strerror", None) or "it is not valid UTF-8 text"
+        raise RenderError(
+            f"Could not read the CSS at {path}: {detail.lower()}."
+        ) from exc