From 4b1c8d16f72bb5d8f2eb8a2e8dde35abdd2f2a88 Mon Sep 17 00:00:00 2001 From: hathach Date: Mon, 29 Jun 2026 10:16:25 +0700 Subject: docs: add build-doc tooling and a README for every example Documentation tooling: - Add the `build-doc` skill and `tools/build_doc.py` wrapper for local Sphinx builds (clean / -W / open). - Enable Markdown (MyST) in conf.py and auto-collect examples/{device,host,dual}/*/README.md into a 3-level Examples nav (Examples > Device/Host/Dual > example), noting each page's source location and normalizing headings to a single H1. - Remove the stale `.claude/commands/build-doc.md`; point the AGENTS.md Documentation section at the skill. Example docs: - Add a README.md for every device/host/dual example: what it does, USB interface table, notable tusb_config.h settings, generic CMake + Make build steps, and how to try it. - Fold each *_freertos variant into its base README, noting the FreeRTOS source path and any RTOS-specific behavior. Generated docs/examples/ output is git-ignored. Builds clean with `sphinx-build -W`. Co-Authored-By: Claude Opus 4.8 (1M context) --- tools/build_doc.py | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100755 tools/build_doc.py (limited to 'tools/build_doc.py') diff --git a/tools/build_doc.py b/tools/build_doc.py new file mode 100755 index 000000000..50e52452a --- /dev/null +++ b/tools/build_doc.py @@ -0,0 +1,50 @@ +#!/usr/bin/env python3 +"""Build the TinyUSB Sphinx documentation locally. + +Thin wrapper around `sphinx-build` so a manual doc build is one command. +`conf.py` auto-collects example READMEs, so no extra steps are needed. + + python3 tools/build_doc.py # build docs/_build/ + python3 tools/build_doc.py -c -W -o # clean, fail on warnings, open result +""" +import argparse +import shutil +import subprocess +import sys +import webbrowser +from pathlib import Path + +TOP = Path(__file__).parent.parent.resolve() +DOCS = TOP / "docs" +BUILD = DOCS / "_build" + + +def main(): + p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + p.add_argument("-c", "--clean", action="store_true", help="remove docs/_build first") + p.add_argument("-W", "--strict", action="store_true", help="treat warnings as errors") + p.add_argument("-o", "--open", action="store_true", help="open the built docs in a browser") + args = p.parse_args() + + if args.clean and BUILD.exists(): + shutil.rmtree(BUILD) + + cmd = ["sphinx-build", "-b", "html"] + if args.strict: + cmd.append("-W") + cmd += [str(DOCS), str(BUILD)] + + print("+", " ".join(cmd)) + rc = subprocess.call(cmd) + if rc != 0: + return rc + + index = BUILD / "index.html" + print(f"\nDocs built: {index}") + if args.open: + webbrowser.open(index.as_uri()) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) -- cgit v1.3.1