diff --git a/.github/workflows/README.md b/.github/workflows/README.md index d8f486386c1..eeea44ff390 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -29,8 +29,8 @@ fire. ### Documentation #### `docs.yml` - Documentation Build -**Triggers:** Pull requests affecting documentation -**Purpose:** Validates documentation builds correctly +**Triggers:** Pull requests and pushes affecting settings inputs, source `.c`/`.h` files, the firmware version in `CMakeLists.txt`, MSP docs inputs/outputs, or the workflow itself +**Purpose:** Regenerates `docs/Settings.md` and the MSP Markdown/JSON references, failing if the checked-in files are stale ### Code Quality diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index edaaecdf3bb..74d5bdac3d4 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,10 +4,22 @@ on: paths: - src/main/fc/settings.yaml - docs/Settings.md + - src/utils/update_cli_docs.py + - 'src/main/**/*.c' + - 'src/main/**/*.h' + - CMakeLists.txt + - 'docs/development/msp/**' + - .github/workflows/docs.yml push: paths: - src/main/fc/settings.yaml - docs/Settings.md + - src/utils/update_cli_docs.py + - 'src/main/**/*.c' + - 'src/main/**/*.h' + - CMakeLists.txt + - 'docs/development/msp/**' + - .github/workflows/docs.yml jobs: settings_md: @@ -25,3 +37,22 @@ jobs: echo "::error ::\"docs/Settings.md\" is not up to date, please run \"src/utils/update_cli_docs.py\"" exit 1 fi + + msp_docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Check that MSP docs are up to date + working-directory: docs/development/msp + run: | + bash gen_docs.sh + if [ -n "$(git status --porcelain -- README.md inav_enums.json inav_enums_ref.md)" ]; then + git status --short -- README.md inav_enums.json inav_enums_ref.md + git diff -- README.md inav_enums.json inav_enums_ref.md + echo "::error ::MSP docs are not up to date, please run 'cd docs/development/msp && bash gen_docs.sh'" + exit 1 + fi diff --git a/docs/development/Development.md b/docs/development/Development.md index a23d0f02b53..35c52301ea5 100755 --- a/docs/development/Development.md +++ b/docs/development/Development.md @@ -168,7 +168,7 @@ Some files are generated from other source files. If your change touches the sou | Source changed | Regenerate with | Output file(s) | CI-enforced? | |---|---|---|---| | `src/main/fc/settings.yaml` | `python3 src/utils/update_cli_docs.py` | `docs/Settings.md` | Yes — `.github/workflows/docs.yml` diffs against a freshly regenerated copy and fails the build if stale | -| Source enum headers under `src/main`, or `docs/development/msp/msp_messages.json` | `docs/development/msp/gen_docs.sh` | `docs/development/msp/inav_enums.json`, `docs/development/msp/README.md` | No — nothing regenerates or diff-checks these in CI, so a forgotten regeneration will ship stale MSP docs silently | +| Source enums in `.c`/`.h` files under `src/main`, firmware version in `CMakeLists.txt`, or MSP docs inputs/scripts under `docs/development/msp` | `cd docs/development/msp && bash gen_docs.sh` | `docs/development/msp/inav_enums.json`, `docs/development/msp/inav_enums_ref.md`, `docs/development/msp/README.md` | Yes — `.github/workflows/docs.yml` regenerates these files and fails the build if stale | `msp_messages.json` itself is hand-authored — there is no script that generates it. When a new MSP handler is added to `fc_msp.c`, a corresponding entry must be added to `msp_messages.json` by hand. See `docs/development/msp/README.md` for the full regeneration and versioning rules. diff --git a/docs/development/msp/get_all_inav_enums_h.py b/docs/development/msp/get_all_inav_enums_h.py index 971d077d5f4..2f21924cc03 100644 --- a/docs/development/msp/get_all_inav_enums_h.py +++ b/docs/development/msp/get_all_inav_enums_h.py @@ -106,7 +106,7 @@ def parse_args(): root = base_dir / sd if not root.is_dir(): continue - for fn in root.rglob('*'): + for fn in sorted(root.rglob('*')): print(fn) if fn.suffix in ('.c', '.h'): txt = fn.read_text(errors='ignore') diff --git a/docs/development/msp/inav_enums.json b/docs/development/msp/inav_enums.json index 7f5e0f6f1cb..ac1f3d01150 100644 --- a/docs/development/msp/inav_enums.json +++ b/docs/development/msp/inav_enums.json @@ -3804,7 +3804,7 @@ "SDCARD_OPERATION_FAILURE": "3" }, "sdcardReceiveBlockStatus_e": { - "_source": "inav/src/main/drivers/sdcard/sdcard_sdio.c", + "_source": "inav/src/main/drivers/sdcard/sdcard_spi.c", "SDCARD_RECEIVE_SUCCESS": "0", "SDCARD_RECEIVE_BLOCK_IN_PROGRESS": "1", "SDCARD_RECEIVE_ERROR": "2" @@ -4189,7 +4189,7 @@ "THR_HI": "(2 << (2 * THROTTLE))" }, "systemState_e": { - "_source": "inav/src/main/fc/fc_init.c", + "_source": "inav/src/main/fc/fc_init.h", "SYSTEM_STATE_INITIALISING": "0", "SYSTEM_STATE_CONFIG_LOADED": "(1 << 0)", "SYSTEM_STATE_SENSORS_READY": "(1 << 1)", diff --git a/docs/development/msp/inav_enums_ref.md b/docs/development/msp/inav_enums_ref.md index 87168663713..e623f3fb34f 100644 --- a/docs/development/msp/inav_enums_ref.md +++ b/docs/development/msp/inav_enums_ref.md @@ -5491,7 +5491,7 @@ --- ## `sdcardReceiveBlockStatus_e` -> Source: ../../../src/main/drivers/sdcard/sdcard_spi.c +> Source: ../../../src/main/drivers/sdcard/sdcard_sdio.c | Enumerator | Value | Condition | |---|---:|---| @@ -5502,7 +5502,7 @@ --- ## `sdcardReceiveBlockStatus_e` -> Source: ../../../src/main/drivers/sdcard/sdcard_sdio.c +> Source: ../../../src/main/drivers/sdcard/sdcard_spi.c | Enumerator | Value | Condition | |---|---:|---| @@ -6074,7 +6074,7 @@ --- ## `systemState_e` -> Source: ../../../src/main/fc/fc_init.h +> Source: ../../../src/main/fc/fc_init.c | Enumerator | Value | Condition | |---|---:|---| @@ -6088,7 +6088,7 @@ --- ## `systemState_e` -> Source: ../../../src/main/fc/fc_init.c +> Source: ../../../src/main/fc/fc_init.h | Enumerator | Value | Condition | |---|---:|---|