Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions contrib/book.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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")
Expand Down Expand Up @@ -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 = {}
Expand All @@ -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.
Expand All @@ -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__":
Expand Down
24 changes: 18 additions & 6 deletions contrib/mermaid_ssr.py
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
#!/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
itself: it takes each diagram from MERMAID_SVG_DIR/<sha256 of its
source>/<theme>.svg, as nix/mermaid.nix renders them, with PLACEHOLDER
standing for the svg id.
"""
import base64
import hashlib
import json
import os
Expand Down Expand Up @@ -69,26 +70,37 @@ 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:
continue

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)


Expand Down
29 changes: 28 additions & 1 deletion contrib/test_book.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,41 @@ 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"
"* [Two](sub/two.md) - The second chapter.\n"
)


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",
[
Expand Down
9 changes: 9 additions & 0 deletions contrib/test_mermaid_ssr.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import base64
import hashlib

import mermaid_ssr
Expand Down Expand Up @@ -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", '<svg id="MERMAID_SSR_ID"/>')
monkeypatch.setenv("MERMAID_SVG_DIR", str(tmp_path))
svg = base64.b64encode(b'<svg id="mermaid-2"/>').decode()
assert mermaid_ssr.image(SOURCE, 2) == (
"\n\n![](data:image/svg+xml;base64,%s)\n\n" % svg)
4 changes: 4 additions & 0 deletions cspell/tooling.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
28 changes: 25 additions & 3 deletions nix/site.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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 ])) ]; }
Expand All @@ -72,7 +94,7 @@
};

packages = {
inherit site;
inherit site pdf;
default = site;
};
};
Expand Down
Loading