amethyst-cli 0.1.0__py3-none-any.whl

amethyst/theme/builtin/css/base.css

@@ -0,0 +1,361 @@
+/* Structural CSS for the PDF pipeline.
+ *
+ * Everything here is either layout that does not belong to a theme, or a
+ * default that a theme overrides. A theme compiles to a `:root` block appended
+ * after this file — after, because two `:root` blocks have the same specificity
+ * and the later one wins. The custom properties below are the values it
+ * replaces, which keeps this stylesheet readable on its own and keeps the PDF
+ * path working with no theme loaded at all.
+ *
+ * One rule for anything added here: it must render without a WeasyPrint
+ * warning. The renderer forwards WeasyPrint's log to the user, so a property it
+ * does not support is not a silent no-op — it is a line of noise on every
+ * single conversion.
+ */
+
+:root {
+  --font-body: "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
+  --font-heading: var(--font-body);
+  --font-mono: ui-monospace, "SF Mono", Menlo, "DejaVu Sans Mono", monospace;
+
+  --size-body: 11pt;
+  --size-small: 9.5pt;
+  --size-code: 0.85em;
+  --size-title: 2.6em;
+  --leading: 1.45;
+  --weight-heading: 600;
+
+  /* Heading sizes, as multiples of the body size. */
+  --size-h1: 2em;
+  --size-h2: 1.5em;
+  --size-h3: 1.22em;
+  --size-h4: 1.05em;
+  --size-h5: 1em;
+  --size-h6: 1em;
+
+  --color-text: #16151a;
+  --color-muted: #5d5a66;
+  --color-accent: #6a3fa0;
+  --color-rule: #d9d6de;
+  --color-fill: #f6f4f8;
+
+  --block-gap: 0.85em;
+  --indent: 1.6em;
+}
+
+/* --- page furniture ---------------------------------------------------- */
+
+/* @page lives in the generated block. Its size and margins come from the theme
+   and the flags, and a paged-media descriptor cannot read a custom property
+   anyway. */
+
+html {
+  font-family: var(--font-body);
+  font-size: var(--size-body);
+  line-height: var(--leading);
+  color: var(--color-text);
+}
+
+body {
+  margin: 0;
+  /* Ragged right. Justified text needs hyphenation to avoid rivers, and
+     hyphenation needs a language declared per document, which nothing sets
+     yet. */
+  text-align: left;
+  orphans: 2;
+  widows: 2;
+}
+
+/* --- front matter ------------------------------------------------------ */
+
+/* The cover and the contents sit on a named page, which is how the generated
+   block takes the running head off them without counting pages: they belong to
+   no section, so there is no section for a head to name. */
+
+.title-page,
+.contents {
+  page: front;
+  break-after: page;
+}
+
+/* Roughly the upper third of the sheet. The Word renderer sets the same gap
+   above its title, in the same multiple of the body size, because neither
+   format has a way to read it off the other. */
+.title-page {
+  padding-top: 8em;
+}
+
+/* Not a heading: an h1 here would open a section, put an entry in the PDF
+   outline and set the running head, none of which a cover should do. */
+.doc-title {
+  font-family: var(--font-heading);
+  font-size: var(--size-title);
+  font-weight: var(--weight-heading);
+  line-height: 1.15;
+  letter-spacing: -0.015em;
+  margin: 0 0 0.3em;
+}
+
+.doc-subtitle {
+  font-size: var(--size-h3);
+  font-weight: 400;
+  line-height: 1.3;
+  color: var(--color-muted);
+  margin: 0 0 3em;
+}
+
+.doc-author {
+  margin: 0 0 0.15em;
+}
+
+.doc-date {
+  font-size: var(--size-small);
+  color: var(--color-muted);
+  margin: 0;
+}
+
+/* --- contents ---------------------------------------------------------- */
+
+/* The contents names no section of its own, and the generated block sets the
+   named string from a heading level that this could well be. A class beats a
+   bare element selector, so this wins wherever that lands. */
+.toc-heading {
+  string-set: section "";
+}
+
+.contents ol {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.contents li {
+  margin: 0 0 0.3em;
+}
+
+.contents a {
+  color: inherit;
+  text-decoration: none;
+}
+
+/* The dots and the page number, which only a paged renderer can fill in:
+   target-counter resolves the href against the page the heading landed on. */
+.contents a::after {
+  content: ' ' leader('.') ' ' target-counter(attr(href), page);
+  color: var(--color-muted);
+}
+
+.contents .toc-1 {
+  font-weight: var(--weight-heading);
+  margin-top: 0.7em;
+}
+
+.contents .toc-2 { padding-left: 1.2em; }
+.contents .toc-3 { padding-left: 2.4em; }
+.contents .toc-4 { padding-left: 3.6em; }
+.contents .toc-5 { padding-left: 4.8em; }
+.contents .toc-6 { padding-left: 6em; }
+
+/* --- headings ---------------------------------------------------------- */
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: var(--font-heading);
+  font-weight: var(--weight-heading);
+  line-height: 1.2;
+  margin: 1.4em 0 0.5em;
+  /* A heading alone at the foot of a page is the most visible typesetting
+     failure there is, and these two rules are the whole fix. */
+  break-after: avoid;
+  break-inside: avoid;
+}
+
+h1 { font-size: var(--size-h1); margin-top: 0; letter-spacing: -0.01em; }
+h2 { font-size: var(--size-h2); }
+h3 { font-size: var(--size-h3); }
+h4 { font-size: var(--size-h4); }
+h5 { font-size: var(--size-h5); }
+h6 { font-size: var(--size-h6); color: var(--color-muted); }
+
+/* --- flow -------------------------------------------------------------- */
+
+p {
+  margin: 0 0 var(--block-gap);
+}
+
+a {
+  color: var(--color-accent);
+  text-decoration: none;
+}
+
+hr {
+  border: none;
+  border-top: 1px solid var(--color-rule);
+  margin: 1.6em 0;
+}
+
+/* --- lists ------------------------------------------------------------- */
+
+ul,
+ol {
+  margin: 0 0 var(--block-gap);
+  padding-left: var(--indent);
+}
+
+li {
+  margin-bottom: 0.2em;
+}
+
+/* Nested lists sit inside their parent item, so their own outer margin would
+   double the gap the item already has. */
+li > ul,
+li > ol {
+  margin-top: 0.2em;
+  margin-bottom: 0;
+}
+
+/* Task lists carry their own bullet in the checkbox. */
+.contains-task-list {
+  list-style: none;
+  padding-left: 0.2em;
+}
+
+/* The browser default stylesheet lays a checkbox out as a block, which puts
+   every task on two lines with the box alone on the first. */
+.task-list-item-checkbox {
+  display: inline-block;
+  width: 0.72em;
+  height: 0.72em;
+  margin-right: 0.45em;
+  vertical-align: -0.02em;
+  border: 1px solid var(--color-muted);
+  border-radius: 2px;
+}
+
+/* --- definition lists -------------------------------------------------- */
+
+dl {
+  margin: 0 0 var(--block-gap);
+}
+
+dt {
+  font-weight: 600;
+}
+
+dd {
+  margin: 0 0 0.5em var(--indent);
+}
+
+/* --- quotes ------------------------------------------------------------ */
+
+blockquote {
+  margin: 0 0 var(--block-gap);
+  padding-left: 1em;
+  border-left: 2px solid var(--color-rule);
+  color: var(--color-muted);
+}
+
+blockquote > :last-child {
+  margin-bottom: 0;
+}
+
+/* --- code -------------------------------------------------------------- */
+
+code,
+kbd,
+samp {
+  font-family: var(--font-mono);
+  font-size: var(--size-code);
+}
+
+:not(pre) > code {
+  background: var(--color-fill);
+  padding: 0.1em 0.28em;
+  border-radius: 3px;
+}
+
+pre {
+  font-family: var(--font-mono);
+  font-size: var(--size-code);
+  line-height: 1.4;
+  background: var(--color-fill);
+  border: 1px solid var(--color-rule);
+  border-radius: 4px;
+  padding: 0.7em 0.9em;
+  margin: 0 0 var(--block-gap);
+  /* A page has no horizontal scrollbar: an over-long line has to wrap or it
+     is simply lost off the edge of the paper. */
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+pre > code {
+  background: none;
+  padding: 0;
+  font-size: inherit;
+}
+
+/* --- tables ------------------------------------------------------------ */
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0 0 var(--block-gap);
+  font-size: var(--size-small);
+}
+
+th,
+td {
+  border: 1px solid var(--color-rule);
+  padding: 0.35em 0.6em;
+  text-align: left;
+  vertical-align: top;
+}
+
+th {
+  background: var(--color-fill);
+  font-weight: 600;
+}
+
+/* A row split across a page break is unreadable; the header repeating is the
+   reason the split is survivable at all. */
+tr {
+  break-inside: avoid;
+}
+
+thead {
+  display: table-header-group;
+}
+
+/* --- figures ----------------------------------------------------------- */
+
+img {
+  max-width: 100%;
+}
+
+/* --- footnotes --------------------------------------------------------- */
+
+.footnotes-sep {
+  margin-top: 2.5em;
+}
+
+.footnotes {
+  font-size: var(--size-small);
+  color: var(--color-muted);
+}
+
+.footnotes p {
+  margin-bottom: 0.35em;
+}
+
+/* Dropped rather than styled. The glyph markdown-it uses for it has no
+   coverage in most serif text fonts, so it sets as a missing-glyph box; and a
+   back-link is a browser affordance that a typeset page does not want, which
+   makes restoring it with a symbol font the wrong repair. */
+.footnote-backref {
+  display: none;
+}

amethyst/theme/builtin/default.toml

@@ -0,0 +1,42 @@
+# Amethyst's default theme.
+#
+# Copy this file, change what you want and pass it with -t path/to/theme.toml.
+# Anything you leave out is taken from here, so a theme can be as short as one
+# section — or one line.
+
+description = "A serif text face, roomy leading and a violet accent."
+
+[fonts]
+# Most-preferred family first; the last one should be a generic family so
+# there is always something to fall back to.
+body = ["Iowan Old Style", "Palatino Linotype", "Palatino", "Georgia", "serif"]
+heading = ["Iowan Old Style", "Palatino Linotype", "Palatino", "Georgia", "serif"]
+mono = ["ui-monospace", "SF Mono", "Menlo", "DejaVu Sans Mono", "monospace"]
+
+[type]
+# The two absolute sizes are points. Everything else on this page is a
+# multiple of `size`, so changing it alone rescales the whole document.
+size = 11
+small = 9.5
+code = 0.85   # a multiple of `size`, for code blocks and inline code
+title = 2.6   # a multiple of `size`, for the title on a title page
+line_height = 1.45
+heading_weight = 600
+# h1 to h6.
+headings = [2, 1.5, 1.22, 1.05, 1, 1]
+
+[colors]
+text = "#16151a"    # body text
+muted = "#5d5a66"   # footnotes, page numbers, quoted text
+accent = "#6a3fa0"  # links
+rule = "#d9d6de"    # borders and horizontal rules
+fill = "#f6f4f8"    # code and table-header backgrounds
+
+[spacing]
+# Multiples of the body size.
+block = 0.85   # the gap after a paragraph, list, table or code block
+indent = 1.6   # how far a list or a definition is indented
+
+[page]
+size = "A4"
+margin = "2cm"

amethyst/theme/builtin/github.toml

@@ -0,0 +1,44 @@
+# GitHub's Markdown look, set for paper.
+#
+# The web page it is modelled on is sans-serif, blue-linked and tightly ruled;
+# what changes here is the measure and the units, because a screen scrolls and
+# a page does not.
+
+description = "GitHub's Markdown look: system sans, blue links, quiet rules."
+
+[fonts]
+# GitHub asks for the reader's own system font first. That is spelled
+# `-apple-system` on the web, which is a keyword rather than a family and
+# means nothing to a PDF renderer or to Word, so the stack names the fonts
+# those actually resolve.
+body = ["Helvetica Neue", "Segoe UI", "Roboto", "Noto Sans", "Arial", "sans-serif"]
+heading = ["Helvetica Neue", "Segoe UI", "Roboto", "Noto Sans", "Arial", "sans-serif"]
+mono = ["SFMono-Regular", "SF Mono", "Menlo", "Consolas", "DejaVu Sans Mono", "monospace"]
+
+[type]
+# A shade smaller than the default theme: a sans face at the same size reads
+# larger than a serif one, and this one is set at GitHub's own 1.5 leading.
+size = 10.5
+small = 9
+code = 0.85
+title = 2.6
+line_height = 1.5
+heading_weight = 600
+# GitHub's own scale, which drops h5 and h6 below the body size rather than
+# leaving them level with it.
+headings = [2, 1.5, 1.25, 1, 0.875, 0.85]
+
+[colors]
+text = "#1f2328"
+muted = "#59636e"
+accent = "#0969da"
+rule = "#d1d9e0"
+fill = "#f6f8fa"
+
+[spacing]
+block = 1        # GitHub's paragraph gap is a full line
+indent = 1.8
+
+[page]
+size = "A4"
+margin = "2cm"

amethyst/theme/to_css.py

@@ -0,0 +1,182 @@
+"""A theme, compiled to CSS: the custom properties, and the page block.
+
+Two blocks come out of here, and they are separate for a reason.
+
+The first is nothing but custom properties. It is appended after ``base.css``
+so that it wins the cascade, and it declares no rules of its own — which is
+what keeps the question of *how* a document is laid out in one file, and the
+question of what it is made of in the theme.
+
+The second is ``@page``, which cannot be done that way. ``size`` and ``margin``
+are at-rule descriptors, so ``size: var(--page-size)`` does not resolve; and a
+margin box sits outside the document tree, inheriting nothing from ``:root``,
+so the page number's own font and colour have to be written out in full.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from amethyst.theme import Theme
+
+#: A family name that needs no quotes: a bare word, which covers the generic
+#: families — quoting ``serif`` would turn it into a search for a font called
+#: "serif" — and the single-word brands. Everything else is quoted.
+BARE_FAMILY = re.compile(r"\A[A-Za-z][A-Za-z0-9-]*\Z")
+
+
+def root_css(theme: Theme) -> str:
+    """The custom properties ``base.css`` reads, as one ``:root`` block."""
+    type_ = theme.type
+    declarations: list[tuple[str, str]] = [
+        ("font-body", font_stack(theme.fonts.body)),
+        ("font-heading", font_stack(theme.fonts.heading)),
+        ("font-mono", font_stack(theme.fonts.mono)),
+        ("", ""),
+        ("size-body", points(type_.size)),
+        ("size-small", points(type_.small)),
+        ("size-code", multiple(type_.code)),
+        ("size-title", multiple(type_.title)),
+        ("leading", number(type_.line_height)),
+        ("weight-heading", str(type_.heading_weight)),
+        ("", ""),
+        *(
+            (f"size-h{level}", multiple(size))
+            for level, size in enumerate(type_.headings, start=1)
+        ),
+        ("", ""),
+        ("color-text", theme.colors.text),
+        ("color-muted", theme.colors.muted),
+        ("color-accent", theme.colors.accent),
+        ("color-rule", theme.colors.rule),
+        ("color-fill", theme.colors.fill),
+        ("", ""),
+        ("block-gap", multiple(theme.spacing.block)),
+        ("indent", multiple(theme.spacing.indent)),
+    ]
+    body = [f"  --{name}: {value};" if name else "" for name, value in declarations]
+    return "\n".join([f"/* theme: {theme.name} */", ":root {", *body, "}", ""])
+
+
+def page_css(
+    theme: Theme,
+    *,
+    page_numbers: bool = True,
+    running_title: str | None = None,
+    running_section: int | None = None,
+    front_matter: bool = False,
+    title_page: bool = False,
+) -> str:
+    """The paged-media block: sheet, margins, page number and running head.
+
+    Everything here is generated rather than written in ``base.css`` because
+    it depends on the document as well as the theme — the title is literal
+    text, and which heading level feeds the running head is decided by
+    counting the document's headings.
+
+    ``running_title`` goes in the top-left corner as a literal string; it is
+    not a named string set from the ``h1``, because a document whose body
+    opens with an ``h1`` of its own would then have the head change halfway
+    down. ``running_section`` is the heading level that feeds the top-right
+    corner, and it *is* a named string, because that one is meant to change.
+    """
+    furniture = [
+        f"    font-family: {font_stack(theme.fonts.body)};",
+        f"    font-size: {points(theme.type.small)};",
+        f"    color: {theme.colors.muted};",
+    ]
+    lines = [
+        "@page {",
+        f"  size: {theme.page.size};",
+        f"  margin: {theme.page.margin};",
+    ]
+    if running_title:
+        lines += [
+            "  @top-left {",
+            f"    content: {css_string(running_title)};",
+            *furniture,
+            "  }",
+        ]
+    if running_section is not None:
+        lines += ["  @top-right {", "    content: string(section);", *furniture, "  }"]
+    if page_numbers:
+        lines += [
+            "  @bottom-center {",
+            "    content: counter(page);",
+            *furniture,
+            "  }",
+        ]
+    lines += ["}", ""]
+
+    if running_title or running_section is not None:
+        # The opening page of a document needs no running head: whatever it
+        # would name is set in full a few centimetres below it.
+        lines += [f"@page :first {{{_no_head(running_title, running_section)} }}", ""]
+    if running_section is not None:
+        lines += [f"h{running_section} {{ string-set: section content(); }}", ""]
+
+    if front_matter:
+        # Front matter belongs to no section and is not the document yet, so
+        # it carries no head — and a cover carries no page number either.
+        lines += [f"@page front {{{_no_head(running_title, running_section)} }}", ""]
+        if title_page:
+            lines += ["@page front:first { @bottom-center { content: none } }", ""]
+    return "\n".join(lines)
+
+
+def _no_head(running_title: str | None, running_section: int | None) -> str:
+    """Empty out whichever margin boxes the running head was put in."""
+    boxes = []
+    if running_title:
+        boxes.append(" @top-left { content: none }")
+    if running_section is not None:
+        boxes.append(" @top-right { content: none }")
+    return "".join(boxes)
+
+
+def css_string(value: str) -> str:
+    """Quote arbitrary text as a CSS string, so a quote in a title is safe.
+
+    The title reaches the stylesheet as a literal because a margin box cannot
+    read a custom property. It is the author's text, though, so it has to be
+    escaped rather than trusted: an unescaped quote would end the string and
+    the rest of the block would be read as something else entirely.
+    """
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    # A newline cannot appear inside a CSS string at all, escaped or not.
+    escaped = " ".join(escaped.split())
+    return f'"{escaped}"'
+
+
+def font_stack(families: Sequence[str]) -> str:
+    """Join family names into a CSS font stack, quoting only what needs it."""
+    return ", ".join(
+        family if BARE_FAMILY.match(family) else f'"{family}"' for family in families
+    )
+
+
+def points(value: float) -> str:
+    """An absolute size, in the unit print is measured in."""
+    return f"{number(value)}pt"
+
+
+def multiple(value: float) -> str:
+    """A size relative to the text it sits in."""
+    return f"{number(value)}em"
+
+
+def number(value: float) -> str:
+    """Write a number the short way: 11 rather than 11.0, 1.45 as it is."""
+    return f"{value:g}"
+
+
+__all__ = [
+    "css_string",
+    "font_stack",
+    "multiple",
+    "number",
+    "page_css",
+    "points",
+    "root_css",
+]