diff --git a/contrib/book.py b/contrib/book.py index 1cf9b79..74f8b3a 100644 --- a/contrib/book.py +++ b/contrib/book.py @@ -7,9 +7,10 @@ relative to docs/, and every chapter must have an entry. The README is the introduction, and the index, with its descriptions, is the contents page. Frontmatter is checked and then dropped, as mdbook would render it -as text. The bundle's other files are copied as they are. +as text. The bundle's other files are copied as they are. A PDF of the +book, if given, is copied too and linked from the contents page. - python3 book.py ROOT + python3 book.py [--pdf FILE] ROOT """ import argparse import posixpath @@ -26,6 +27,8 @@ # As set in book.toml. SRC = "src" CONTENTS = "contents.md" +# mdbook copies src/ files that are not chapters into the site. +PDF = "fungi-docs.pdf" GENERATED = ("README.md", "SUMMARY.md", CONTENTS) STATUSES = ("draft", "stable", "deprecated") RESERVED = ("index.md", "log.md") @@ -92,14 +95,15 @@ def summary(index, pages): return "\n".join(out) + "\n" -def contents(index): - """The contents page: the index with its descriptions, its parts one - heading level down.""" +def contents(index, pdf): + """The contents page: a link to the PDF if `pdf`, then the index with + its descriptions, its parts one heading level down.""" body = re.sub(r"^# ", "## ", strip_frontmatter(index), flags=re.MULTILINE) - return "# Contents\n\n" + body + link = f"Also as a [PDF]({PDF}).\n\n" if pdf else "" + return "# Contents\n\n" + link + body -def assemble(root): +def assemble(root, pdf=None): docs, out = root / DOCS, root / SRC index = (docs / "index.md").read_text() pages = {} @@ -119,8 +123,9 @@ def assemble(root): generated = { "README.md": re.sub(r"(?<=\]\()docs/", "", (root / "README.md").read_text()), "SUMMARY.md": summary(index, pages), - CONTENTS: contents(index), + CONTENTS: contents(index, pdf is not None), } + pdf_bytes = pdf.read_bytes() if pdf is not None else None # mdbook serve watches src/ itself and skips what the root .gitignore # matches, so src/ is emptied rather than replaced, and ignores itself # before anything else is written to it. @@ -144,12 +149,16 @@ def assemble(root): for name, text in pages.items(): (out / name).parent.mkdir(parents=True, exist_ok=True) (out / name).write_text(strip_frontmatter(text)) + if pdf_bytes is not None: + (out / PDF).write_bytes(pdf_bytes) def main(argv=None): p = argparse.ArgumentParser(description=__doc__.splitlines()[0]) p.add_argument("root", type=Path) - assemble(p.parse_args(argv).root) + p.add_argument("--pdf", type=Path, help="the book as a PDF") + args = p.parse_args(argv) + assemble(args.root, args.pdf) if __name__ == "__main__": diff --git a/contrib/mermaid_ssr.py b/contrib/mermaid_ssr.py index 239502e..af5283a 100644 --- a/contrib/mermaid_ssr.py +++ b/contrib/mermaid_ssr.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""mdbook preprocessor: render ```mermaid blocks to inline SVG with mmdc. +"""mdbook preprocessor: render ```mermaid blocks to SVG with mmdc. Expects the `mmdc` from nix/mermaid.nix, which comes wrapped with the headless chromium it drives. If MERMAID_SVG_DIR is set, it renders nothing @@ -7,6 +7,7 @@ source>/.svg, as nix/mermaid.nix renders them, with PLACEHOLDER standing for the svg id. """ +import base64 import hashlib import json import os @@ -69,7 +70,17 @@ def block(source, index): ) + "\n\n" -def walk(items, counter): +def image(source, index): + """The light theme of one diagram, as an image for the pandoc renderer. + + Inline svg is html, which pandoc drops from a LaTeX document. + """ + svg = render(source, "default", "mermaid-%d" % index) + return "\n\n![](data:image/svg+xml;base64,%s)\n\n" % base64.b64encode( + svg.encode()).decode() + + +def walk(items, counter, emit): for item in items: chapter = item.get("Chapter") if not chapter: @@ -77,18 +88,19 @@ def walk(items, counter): def substitute(match): counter[0] += 1 - return block(match.group("body"), counter[0]) + return emit(match.group("body"), counter[0]) chapter["content"] = FENCE.sub(substitute, chapter["content"]) - walk(chapter["sub_items"], counter) + walk(chapter["sub_items"], counter, emit) def main(): if len(sys.argv) > 1 and sys.argv[1] == "supports": sys.exit(0) - _context, book = json.load(sys.stdin) + context, book = json.load(sys.stdin) + emit = image if context["renderer"] == "pandoc" else block # mdbook 0.5 renamed the top level key from `sections` to `items`. - walk(book.get("items", book.get("sections")), [0]) + walk(book.get("items", book.get("sections")), [0], emit) json.dump(book, sys.stdout) diff --git a/contrib/test_book.py b/contrib/test_book.py index 25f5c09..7b984c2 100644 --- a/contrib/test_book.py +++ b/contrib/test_book.py @@ -36,7 +36,7 @@ def test_summary_follows_the_index_without_descriptions(): def test_contents_keep_descriptions_under_one_title(): - assert book.contents(INDEX) == ( + assert book.contents(INDEX, pdf=False) == ( "# Contents\n\n" "## Part\n\n" "* [One](one.md) - The first chapter.\n" @@ -44,6 +44,33 @@ def test_contents_keep_descriptions_under_one_title(): ) +def test_assembly_copies_the_pdf_it_links(tmp_path): + root, out = tmp_path / "root", tmp_path / "root" / "src" + (root / "docs").mkdir(parents=True) + (root / "README.md").write_text("# Intro\n") + (root / "docs" / "index.md").write_text("# Part\n") + pdf = tmp_path / "book.pdf" + pdf.write_bytes(b"%PDF") + book.assemble(root) + assert "PDF" not in (out / "contents.md").read_text() + assert not (out / "fungi-docs.pdf").exists() + book.assemble(root, pdf) + assert "[PDF](fungi-docs.pdf)" in (out / "contents.md").read_text() + assert (out / "fungi-docs.pdf").read_bytes() == b"%PDF" + + +def test_a_missing_pdf_leaves_src_as_it_was(tmp_path): + root, out = tmp_path / "root", tmp_path / "root" / "src" + (root / "docs").mkdir(parents=True) + (root / "README.md").write_text("# Intro\n") + (root / "docs" / "index.md").write_text("# Part\n") + book.assemble(root) + before = (out / "contents.md").read_text() + with pytest.raises(FileNotFoundError): + book.assemble(root, tmp_path / "missing.pdf") + assert (out / "contents.md").read_text() == before + + @pytest.mark.parametrize( "line, error", [ diff --git a/contrib/test_mermaid_ssr.py b/contrib/test_mermaid_ssr.py index 18149cb..8c7ab0b 100644 --- a/contrib/test_mermaid_ssr.py +++ b/contrib/test_mermaid_ssr.py @@ -1,3 +1,4 @@ +import base64 import hashlib import mermaid_ssr @@ -25,3 +26,11 @@ def test_diagram_missing_from_the_prerendered_set_fails(tmp_path, monkeypatch): monkeypatch.setenv("MERMAID_SVG_DIR", str(tmp_path)) with pytest.raises(SystemExit): mermaid_ssr.render(SOURCE + " b --> c\n", "default", "mermaid-1-light") + + +def test_pandoc_gets_the_light_diagram_as_an_image(tmp_path, monkeypatch): + prerender(tmp_path, SOURCE, "default", '') + monkeypatch.setenv("MERMAID_SVG_DIR", str(tmp_path)) + svg = base64.b64encode(b'').decode() + assert mermaid_ssr.image(SOURCE, 2) == ( + "\n\n![](data:image/svg+xml;base64,%s)\n\n" % svg) diff --git a/cspell/tooling.txt b/cspell/tooling.txt index 32ceda8..f825ec2 100644 --- a/cspell/tooling.txt +++ b/cspell/tooling.txt @@ -10,17 +10,21 @@ foldl fontconfig Graphviz KaTeX +librsvg lzanini mdBook mmdc NixOS nixpkgs +pandoc pkgs prerender prerendered pytest PyYAML +rsvg stdenv svgs +texlive toplevel unfetched diff --git a/nix/site.nix b/nix/site.nix index a8d0f35..9ccf5fe 100644 --- a/nix/site.nix +++ b/nix/site.nix @@ -41,16 +41,38 @@ buildPhase = '' export FONTCONFIG_FILE=${fontconfig} - python3 contrib/book.py . + python3 contrib/book.py --pdf ${pdf}/fungi-docs.pdf . mdbook build -d $out ''; dontInstall = true; }; + + pdf = site.overrideAttrs (old: { + name = "fungi-docs-pdf"; + nativeBuildInputs = old.nativeBuildInputs ++ [ + pkgs.mdbook-pandoc + pkgs.pandoc + # pandoc converts the mermaid SVGs to PDF with rsvg-convert. + pkgs.librsvg + pkgs.texliveSmall + ]; + # MDBOOK_OUTPUT replaces the [output] table of book.toml, so this + # build runs only the pandoc renderer. + MDBOOK_OUTPUT = builtins.toJSON { + pandoc.profile.pdf.output-file = "fungi-docs.pdf"; + }; + buildPhase = '' + export FONTCONFIG_FILE=${fontconfig} + python3 contrib/book.py . + mdbook build -d book + install -D book/pdf/fungi-docs.pdf $out/fungi-docs.pdf + ''; + }); in { checks = { - inherit site; + inherit site pdf; book = pkgs.runCommand "book-tests" { nativeBuildInputs = [ (pkgs.python3.withPackages (ps: [ ps.pytest ps.pyyaml ])) ]; } @@ -72,7 +94,7 @@ }; packages = { - inherit site; + inherit site pdf; default = site; }; };