✨ 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:
parent
e41e71cc78
commit
1a41a456d4
80 changed files with 14112 additions and 1218 deletions
72
tools/doccheck/extract.py
Normal file
72
tools/doccheck/extract.py
Normal 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()
|
||||
Loading…
Add table
Add a link
Reference in a new issue