✨ Serve the PageTop guides with pagetop-mdbook

Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.

Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.

Move the configuration to config/common.toml and translate the README
to English.
This commit is contained in:
Manuel Cillero 2026-10-17 08:06:02 +02:00
parent e41e71cc78
commit 1a41a456d4
80 changed files with 14112 additions and 1218 deletions

72
tools/doccheck/extract.py Normal file
View file

@ -0,0 +1,72 @@
"""Extracts the Rust code blocks of an mdBook book into the doccheck crate.
Usage: extract.py <book src dir> <doccheck dir>
Every ```rust block becomes a file, after removing the `# ` prefix of the lines that mdBook hides:
- Blocks marked `ignore` are skipped (loose fragments that are not meant to compile).
- Blocks with `#[pagetop::test]` go to `tests/generated_*.rs` and run with `cargo test`.
- The rest go to `examples/*.rs`. Those not marked `no_run` end in `_run` and are executed, so
their `assert!` are checked. Blocks without `fn main` get one: statements are wrapped in it, like
rustdoc does; items get an empty one.
"""
import pathlib
import re
import sys
STATEMENT = re.compile(r"(let |assert|[A-Za-z_:]+::[a-z_]+\(|[a-z_]+\.)")
HEADER = re.compile(r"(use |#!|include_locales!)")
def unhide(code):
lines = []
for line in code.splitlines():
if line.startswith("# "):
line = line[2:]
elif line == "#":
line = ""
lines.append(line)
return lines
def with_main(lines):
code = "\n".join(lines)
if "fn main" in code:
return code
if any(STATEMENT.match(line) for line in lines):
head = [line for line in lines if HEADER.match(line)]
body = [line for line in lines if not HEADER.match(line)]
return "\n".join(head) + "\nfn main() {\n" + "\n".join(body) + "\n}\n"
return code + "\n\nfn main() {}\n"
def main():
book, crate = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])
examples, tests = crate / "examples", crate / "tests"
examples.mkdir(exist_ok=True)
for old in list(examples.glob("*.rs")) + list(tests.glob("generated_*.rs")):
old.unlink()
count = {"examples": 0, "tests": 0}
for md in sorted(book.rglob("*.md")):
blocks = re.finditer(r"```rust([^\n]*)\n(.*?)```", md.read_text(), re.S)
for i, block in enumerate(blocks):
attrs, lines = block.group(1), unhide(block.group(2))
if "ignore" in attrs:
continue
name = md.relative_to(book).with_suffix("").as_posix()
stem = re.sub(r"[^a-z0-9]", "_", name.lower()) + f"_{i:02d}"
prelude = "#![allow(dead_code, unused)]\n"
if any("#[pagetop::test]" in line for line in lines):
(tests / f"generated_{stem}.rs").write_text(prelude + "\n".join(lines) + "\n")
count["tests"] += 1
else:
suffix = "" if "no_run" in attrs else "_run"
(examples / f"{stem}{suffix}.rs").write_text(prelude + with_main(lines))
count["examples"] += 1
print(f"{count['examples']} examples and {count['tests']} tests extracted")
if __name__ == "__main__":
main()