"""Extracts the Rust code blocks of an mdBook book into the doccheck crate. Usage: extract.py 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()