diff --git a/docs/build.py b/docs/build.py index 78453fcb..bea28189 100644 --- a/docs/build.py +++ b/docs/build.py @@ -2,7 +2,8 @@ """Build API docs using pdoc. Invoked via ``nox -s docs``.""" import ast -import shutil +from datetime import datetime, timezone +import subprocess from pathlib import Path import pkgutil import importlib @@ -11,17 +12,12 @@ import pdoc import pycyphal2 -OUTPUT_DIRECTORY = Path("html_docs") -EXAMPLES_DIRECTORY = Path("examples") - - -def _discover_examples(directory: Path) -> list[Path]: - if not directory.is_dir(): - raise RuntimeError(f"Examples directory {directory!s} not found while building docs") - examples = sorted(path for path in directory.rglob("*.py") if path.is_file()) - if not examples: - raise RuntimeError(f"No example scripts found under {directory!s} while building docs") - return examples +REPOSITORY_ROOT = Path(__file__).resolve().parents[1] +OUTPUT_DIRECTORY = REPOSITORY_ROOT / "html_docs" +EXAMPLES_DIRECTORY = REPOSITORY_ROOT / "examples" +REPOSITORY_URL = "https://github.com/OpenCyphal/pycyphal" +REVISION = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip() +REPOSITORY_REVISION_ROOT_URL = f"{REPOSITORY_URL}/blob/{REVISION}" def _load_summary(path: Path) -> str: @@ -39,33 +35,17 @@ def _load_summary(path: Path) -> str: return "" -def _make_examples_section(examples: list[Path]) -> str: - if not examples: - return "" +def _inject_examples_section() -> None: lines = ["## Examples", "", "Runnable examples:"] - for path in examples: - relative = path.relative_to(EXAMPLES_DIRECTORY).as_posix() + for path in sorted(EXAMPLES_DIRECTORY.rglob("*.py")): + source = path.relative_to(REPOSITORY_ROOT).as_posix() summary = _load_summary(path) suffix = f" - {summary}" if summary else "" - lines.append(f"- [`examples/{relative}`](examples/{relative}){suffix}") - return "\n".join(lines) + "\n" - - -def _inject_examples_section(examples: list[Path]) -> None: - section = _make_examples_section(examples) - doc = pycyphal2.__doc__ or "" - pycyphal2.__doc__ = doc.rstrip() + f"\n\n{section}" - - -def _copy_examples(examples_source: Path, output_directory: Path, examples: list[Path]) -> None: - destination = output_directory / examples_source.name - shutil.rmtree(destination, ignore_errors=True) - if not examples: - return - for source in examples: - target = destination / source.relative_to(examples_source) - target.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(source, target) + lines.append( + f'- {path.name}{suffix}' + ) + pycyphal2.__doc__ = pycyphal2.__doc__.rstrip() + "\n\n" + "\n".join(lines) + "\n" def main() -> None: @@ -84,13 +64,16 @@ def main() -> None: if hasattr(parent, "__all__") and leaf not in parent.__all__: parent.__all__.append(leaf) + now = datetime.now(timezone.utc).isoformat(timespec='seconds') + # Customization is necessary to expose special members like __aiter__, __call__, etc. # We also use it to tweak the colors. - pdoc.render.configure(template_directory=Path(__file__).resolve().with_name("pdoc")) - examples = _discover_examples(EXAMPLES_DIRECTORY) - _inject_examples_section(examples) + pdoc.render.configure( + template_directory=Path(__file__).resolve().with_name("pdoc"), + footer_text=f"{now} #{REVISION} v{pycyphal2.__version__}", + ) + _inject_examples_section() pdoc.pdoc("pycyphal2", output_directory=OUTPUT_DIRECTORY) - _copy_examples(EXAMPLES_DIRECTORY, OUTPUT_DIRECTORY, examples) if __name__ == "__main__": diff --git a/docs/pdoc/custom.css b/docs/pdoc/custom.css new file mode 100644 index 00000000..f982c964 --- /dev/null +++ b/docs/pdoc/custom.css @@ -0,0 +1,15 @@ +@import url("https://fonts.googleapis.com/css2?family=Ubuntu+Mono:wght@400;700&display=swap"); + +.pdoc { + font-family: "Ubuntu Mono", monospace; +} + +@media (min-width: 770px) { + main.pdoc { + width: calc(90rem + var(--sidebar-width)); + } +} + +main.pdoc .docstring h3 { + font-size: 1.2rem; +} diff --git a/docs/pdoc/theme.css b/docs/pdoc/theme.css index 52dc1401..d7970203 100644 --- a/docs/pdoc/theme.css +++ b/docs/pdoc/theme.css @@ -18,7 +18,3 @@ --def: #FC6D09; --annotation: #7aa2ff; } - -main.pdoc .docstring h3 { - font-size: 1.2rem; -}