From ba32b46ebd5304812d521cd30cfdb5b284341f69 Mon Sep 17 00:00:00 2001 From: hathach Date: Mon, 29 Jun 2026 10:42:41 +0700 Subject: [PATCH] docs: address Copilot review on the example READMEs - Order CFG_TUH_DEVICE_MAX before CFG_TUH_HID in the host config snippets (cdc_msc_hid, hid_controller) so the documented snippet has no forward macro reference when copied into tusb_config.h. - Fix stale `examples.rst` references: the generator now writes per-group `docs/examples//index.rst` pages, so update the conf.py comment and the build-doc SKILL.md accordingly. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/build-doc/SKILL.md | 2 +- docs/conf.py | 2 +- examples/host/cdc_msc_hid/README.md | 2 +- examples/host/hid_controller/README.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/skills/build-doc/SKILL.md b/.claude/skills/build-doc/SKILL.md index 401cb31ad..73544b18a 100644 --- a/.claude/skills/build-doc/SKILL.md +++ b/.claude/skills/build-doc/SKILL.md @@ -14,7 +14,7 @@ python3 tools/build_doc.py -o # build docs/_build/ and open it `tools/build_doc.py` wraps `sphinx-build`: `-c` clean, `-W` fail on warnings, `-o` open. Raw form: `sphinx-build -b html docs docs/_build`. -- Pages can be `.rst` or `.md` (MyST). Example `README.md`s under `examples/{device,host,dual}/*/` are **auto-collected** at build time into `docs/examples/` + `examples.rst` (both git-ignored) — add/rename an example and just rebuild; edit the source README, never the generated copies. +- Pages can be `.rst` or `.md` (MyST). Example `README.md`s under `examples/{device,host,dual}/*/` are **auto-collected** at build time into `docs/examples/` (per-group `index` pages, git-ignored) — add/rename an example and just rebuild; edit the source README, never the generated copies. - Watch the output for `WARNING:` (broken refs, missing toctree entries). ## Regenerate after adding a board or dependency diff --git a/docs/conf.py b/docs/conf.py index 4a1a7adc2..c6d04bff5 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -83,7 +83,7 @@ def preprocess_readme(): preprocess_readme() -# scan example READMEs into docs/examples/ and (re)generate examples.rst +# scan example READMEs into docs/examples/ and generate a per-group index page EXAMPLE_GROUPS = ('device', 'host', 'dual') _HEADING_RE = re.compile(r'^(#{1,6})(\s.*)$') diff --git a/examples/host/cdc_msc_hid/README.md b/examples/host/cdc_msc_hid/README.md index b59c17678..74b3f5317 100644 --- a/examples/host/cdc_msc_hid/README.md +++ b/examples/host/cdc_msc_hid/README.md @@ -20,6 +20,7 @@ Notable `tusb_config.h` settings: ```c #define CFG_TUH_ENABLED 1 #define CFG_TUH_HUB 1 +#define CFG_TUH_DEVICE_MAX (3*CFG_TUH_HUB + 1) #define CFG_TUH_CDC 1 #define CFG_TUH_CDC_FTDI 1 #define CFG_TUH_CDC_CP210X 1 @@ -27,7 +28,6 @@ Notable `tusb_config.h` settings: #define CFG_TUH_CDC_PL2303 1 #define CFG_TUH_HID (3*CFG_TUH_DEVICE_MAX) #define CFG_TUH_MSC 1 -#define CFG_TUH_DEVICE_MAX (3*CFG_TUH_HUB + 1) #define CFG_TUH_HID_EPIN_BUFSIZE 64 #define CFG_TUH_HID_EPOUT_BUFSIZE 64 #define CFG_TUH_CDC_LINE_CONTROL_ON_ENUM (CDC_CONTROL_LINE_STATE_DTR | CDC_CONTROL_LINE_STATE_RTS) diff --git a/examples/host/hid_controller/README.md b/examples/host/hid_controller/README.md index 861f89c5e..02dac493f 100644 --- a/examples/host/hid_controller/README.md +++ b/examples/host/hid_controller/README.md @@ -22,8 +22,8 @@ Notable `tusb_config.h` settings: ```c #define CFG_TUH_ENABLED 1 #define CFG_TUH_HUB 0 -#define CFG_TUH_HID (3*CFG_TUH_DEVICE_MAX) #define CFG_TUH_DEVICE_MAX (3*CFG_TUH_HUB + 1) +#define CFG_TUH_HID (3*CFG_TUH_DEVICE_MAX) #define CFG_TUH_HID_EP_BUFSIZE 64 ```