From 59fa7a4a7d19a28c8bd3fdeea752e4ba8641e784 Mon Sep 17 00:00:00 2001 From: Alex E <57109942+alexenr02@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:51:33 -0600 Subject: [PATCH] docs(modules): add auto-generated disclaimer to every module reference page (#29673) Only modules_main.md told readers that the module reference is generated from source. The per-category pages (modules_driver.md, modules_system.md, ...) and the per-subcategory pages (modules_driver_imu.md, ...) had no such note, so contributors kept fixing typos directly in docs/en/modules/ and the next metadata sync silently reverted them (see #29614). Emit a `::: info` block right under the H1 of every category and subcategory page. The wording follows the existing disclaimers on the airframe reference and the uORB message index: it links to the generator script and names the `make module_documentation` target. docs/en/modules/*.md are regenerated with the updated generator and run through Prettier, mirroring what the docs-orchestrator metadata sync does on main, so the diff is only the new note. Fixes #29624 Assisted-by: Claude:claude-fable-5-1 Signed-off-by: Alex E --- Tools/px4moduledoc/markdownout.py | 13 ++++++++++++- docs/en/modules/modules_autotune.md | 5 +++++ docs/en/modules/modules_command.md | 5 +++++ docs/en/modules/modules_communication.md | 5 +++++ docs/en/modules/modules_controller.md | 5 +++++ docs/en/modules/modules_driver.md | 5 +++++ docs/en/modules/modules_driver_adc.md | 5 +++++ docs/en/modules/modules_driver_airspeed_sensor.md | 5 +++++ docs/en/modules/modules_driver_baro.md | 5 +++++ docs/en/modules/modules_driver_camera.md | 5 +++++ docs/en/modules/modules_driver_distance_sensor.md | 5 +++++ docs/en/modules/modules_driver_imu.md | 5 +++++ docs/en/modules/modules_driver_ins.md | 5 +++++ docs/en/modules/modules_driver_magnetometer.md | 5 +++++ docs/en/modules/modules_driver_optical_flow.md | 5 +++++ docs/en/modules/modules_driver_radio_control.md | 5 +++++ docs/en/modules/modules_driver_rpm_sensor.md | 5 +++++ docs/en/modules/modules_driver_transponder.md | 5 +++++ docs/en/modules/modules_estimator.md | 5 +++++ docs/en/modules/modules_simulation.md | 5 +++++ docs/en/modules/modules_system.md | 5 +++++ docs/en/modules/modules_template.md | 5 +++++ 22 files changed, 117 insertions(+), 1 deletion(-) diff --git a/Tools/px4moduledoc/markdownout.py b/Tools/px4moduledoc/markdownout.py index 783ee620b0f..f41b6c29354 100644 --- a/Tools/px4moduledoc/markdownout.py +++ b/Tools/px4moduledoc/markdownout.py @@ -7,6 +7,15 @@ from xml.sax.saxutils import escape import codecs import os +# Shown at the top of every category/subcategory page so readers know these +# files are generated and must be fixed in the module source, not in docs/. +AUTOGEN_NOTE = """ +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: +""" + class MarkdownOutput(): def __init__(self, module_groups): @@ -45,7 +54,8 @@ The generated files will be written to the `modules` directory. self._outputs['main'] = result for category in sorted(module_groups): - result = f"# Modules Reference: {category.capitalize()}\n\n" + result = f"# Modules Reference: {category.capitalize()}\n" + result += AUTOGEN_NOTE + '\n' subcategories = module_groups[category] if len(subcategories) > 1: @@ -59,6 +69,7 @@ The generated files will be written to the `modules` directory. # add a sub-page for the subcategory result_subpage = f'# Modules Reference: {subcategory_label} ({category.capitalize()})\n' + result_subpage += AUTOGEN_NOTE result_subpage += self._ProcessModules(subcategories[subcategory]) self._outputs[subcategory_file_name] = result_subpage diff --git a/docs/en/modules/modules_autotune.md b/docs/en/modules/modules_autotune.md index f0570f89259..7fa098d536f 100644 --- a/docs/en/modules/modules_autotune.md +++ b/docs/en/modules/modules_autotune.md @@ -1,5 +1,10 @@ # Modules Reference: Autotune +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## fw_autotune_attitude_control Source: [modules/fw_autotune_attitude_control](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/fw_autotune_attitude_control) diff --git a/docs/en/modules/modules_command.md b/docs/en/modules/modules_command.md index d41936fe85c..20811ea991a 100644 --- a/docs/en/modules/modules_command.md +++ b/docs/en/modules/modules_command.md @@ -1,5 +1,10 @@ # Modules Reference: Command +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## actuator_test Source: [systemcmds/actuator_test](https://github.com/PX4/PX4-Autopilot/tree/main/src/systemcmds/actuator_test) diff --git a/docs/en/modules/modules_communication.md b/docs/en/modules/modules_communication.md index 4ddbb2d74dd..a5076c6ff95 100644 --- a/docs/en/modules/modules_communication.md +++ b/docs/en/modules/modules_communication.md @@ -1,5 +1,10 @@ # Modules Reference: Communication +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## frsky_telemetry Source: [drivers/telemetry/frsky_telemetry](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/telemetry/frsky_telemetry) diff --git a/docs/en/modules/modules_controller.md b/docs/en/modules/modules_controller.md index 0cc42590830..ba32e498d34 100644 --- a/docs/en/modules/modules_controller.md +++ b/docs/en/modules/modules_controller.md @@ -1,5 +1,10 @@ # Modules Reference: Controller +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## airship_att_control Source: [modules/airship_att_control](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/airship_att_control) diff --git a/docs/en/modules/modules_driver.md b/docs/en/modules/modules_driver.md index a0e56b273f9..e5f414d3130 100644 --- a/docs/en/modules/modules_driver.md +++ b/docs/en/modules/modules_driver.md @@ -1,5 +1,10 @@ # Modules Reference: Driver +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + Subcategories: - [Adc](modules_driver_adc.md) diff --git a/docs/en/modules/modules_driver_adc.md b/docs/en/modules/modules_driver_adc.md index aa733a88a87..918c36f077c 100644 --- a/docs/en/modules/modules_driver_adc.md +++ b/docs/en/modules/modules_driver_adc.md @@ -1,5 +1,10 @@ # Modules Reference: Adc (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## ADS7128 Source: [drivers/adc/ads7128](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/adc/ads7128) diff --git a/docs/en/modules/modules_driver_airspeed_sensor.md b/docs/en/modules/modules_driver_airspeed_sensor.md index 504f6bbbce9..fc81ce421b1 100644 --- a/docs/en/modules/modules_driver_airspeed_sensor.md +++ b/docs/en/modules/modules_driver_airspeed_sensor.md @@ -1,5 +1,10 @@ # Modules Reference: Airspeed Sensor (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## asp5033 Source: [drivers/differential_pressure/asp5033](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/differential_pressure/asp5033) diff --git a/docs/en/modules/modules_driver_baro.md b/docs/en/modules/modules_driver_baro.md index 767c73da79a..8a8ca520cdc 100644 --- a/docs/en/modules/modules_driver_baro.md +++ b/docs/en/modules/modules_driver_baro.md @@ -1,5 +1,10 @@ # Modules Reference: Baro (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## bmp280 Source: [drivers/barometer/bmp280](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/barometer/bmp280) diff --git a/docs/en/modules/modules_driver_camera.md b/docs/en/modules/modules_driver_camera.md index ebc42416a79..716f0554d4a 100644 --- a/docs/en/modules/modules_driver_camera.md +++ b/docs/en/modules/modules_driver_camera.md @@ -1,5 +1,10 @@ # Modules Reference: Camera (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## camera_trigger Source: [drivers/camera_trigger](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/camera_trigger) diff --git a/docs/en/modules/modules_driver_distance_sensor.md b/docs/en/modules/modules_driver_distance_sensor.md index 02e65c6eebc..61548f0287b 100644 --- a/docs/en/modules/modules_driver_distance_sensor.md +++ b/docs/en/modules/modules_driver_distance_sensor.md @@ -1,5 +1,10 @@ # Modules Reference: Distance Sensor (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## afbrs50 Source: [drivers/distance_sensor/broadcom/afbrs50](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/distance_sensor/broadcom/afbrs50) diff --git a/docs/en/modules/modules_driver_imu.md b/docs/en/modules/modules_driver_imu.md index 2af402ed9dc..588d70ce830 100644 --- a/docs/en/modules/modules_driver_imu.md +++ b/docs/en/modules/modules_driver_imu.md @@ -1,5 +1,10 @@ # Modules Reference: Imu (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## adis16448 Source: [drivers/imu/analog_devices/adis16448](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/imu/analog_devices/adis16448) diff --git a/docs/en/modules/modules_driver_ins.md b/docs/en/modules/modules_driver_ins.md index 283e3407c27..ca193c28e8d 100644 --- a/docs/en/modules/modules_driver_ins.md +++ b/docs/en/modules/modules_driver_ins.md @@ -1,5 +1,10 @@ # Modules Reference: Ins (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## MicroStrain Source: [drivers/ins/microstrain](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/ins/microstrain) diff --git a/docs/en/modules/modules_driver_magnetometer.md b/docs/en/modules/modules_driver_magnetometer.md index 1b775f3dae5..c044cf0ad80 100644 --- a/docs/en/modules/modules_driver_magnetometer.md +++ b/docs/en/modules/modules_driver_magnetometer.md @@ -1,5 +1,10 @@ # Modules Reference: Magnetometer (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## af9838 Source: [drivers/magnetometer/voltafield/af9838](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/magnetometer/voltafield/af9838) diff --git a/docs/en/modules/modules_driver_optical_flow.md b/docs/en/modules/modules_driver_optical_flow.md index d69b6d28ccd..6aeb691babb 100644 --- a/docs/en/modules/modules_driver_optical_flow.md +++ b/docs/en/modules/modules_driver_optical_flow.md @@ -1,5 +1,10 @@ # Modules Reference: Optical Flow (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## thoneflow Source: [drivers/optical_flow/thoneflow](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/optical_flow/thoneflow) diff --git a/docs/en/modules/modules_driver_radio_control.md b/docs/en/modules/modules_driver_radio_control.md index 204eb4beea0..27c6105ac3a 100644 --- a/docs/en/modules/modules_driver_radio_control.md +++ b/docs/en/modules/modules_driver_radio_control.md @@ -1,5 +1,10 @@ # Modules Reference: Radio Control (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## crsf_rc Source: [drivers/rc/crsf_rc](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/rc/crsf_rc) diff --git a/docs/en/modules/modules_driver_rpm_sensor.md b/docs/en/modules/modules_driver_rpm_sensor.md index b03fb766a42..08fcec2af2d 100644 --- a/docs/en/modules/modules_driver_rpm_sensor.md +++ b/docs/en/modules/modules_driver_rpm_sensor.md @@ -1,5 +1,10 @@ # Modules Reference: Rpm Sensor (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## pcf8583 Source: [drivers/rpm/pcf8583](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/rpm/pcf8583) diff --git a/docs/en/modules/modules_driver_transponder.md b/docs/en/modules/modules_driver_transponder.md index dd9e4bdeceb..a05fc4f608b 100644 --- a/docs/en/modules/modules_driver_transponder.md +++ b/docs/en/modules/modules_driver_transponder.md @@ -1,5 +1,10 @@ # Modules Reference: Transponder (Driver) +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## sagetech_mxs Source: [drivers/transponder/sagetech_mxs](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/transponder/sagetech_mxs) diff --git a/docs/en/modules/modules_estimator.md b/docs/en/modules/modules_estimator.md index 60af0e8c65e..626d577bb82 100644 --- a/docs/en/modules/modules_estimator.md +++ b/docs/en/modules/modules_estimator.md @@ -1,5 +1,10 @@ # Modules Reference: Estimator +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## AttitudeEstimatorQ Source: [modules/attitude_estimator_q](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/attitude_estimator_q) diff --git a/docs/en/modules/modules_simulation.md b/docs/en/modules/modules_simulation.md index f0a12f66048..e37eaf2415e 100644 --- a/docs/en/modules/modules_simulation.md +++ b/docs/en/modules/modules_simulation.md @@ -1,5 +1,10 @@ # Modules Reference: Simulation +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## simulator_sih Source: [modules/simulation/simulator_sih](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/simulator_sih) diff --git a/docs/en/modules/modules_system.md b/docs/en/modules/modules_system.md index 8389bdc6a67..d608b67d34d 100644 --- a/docs/en/modules/modules_system.md +++ b/docs/en/modules/modules_system.md @@ -1,5 +1,10 @@ # Modules Reference: System +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## battery_simulator Source: [modules/simulation/battery_simulator](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/battery_simulator) diff --git a/docs/en/modules/modules_template.md b/docs/en/modules/modules_template.md index 10e0e16f057..cf39ed1e696 100644 --- a/docs/en/modules/modules_template.md +++ b/docs/en/modules/modules_template.md @@ -1,5 +1,10 @@ # Modules Reference: Template +::: info +**This page is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/px4moduledoc/markdownout.py) from the source code** using the build command: `make module_documentation`. +Do not edit it directly; fix the module documentation in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) source instead. +::: + ## mc_raptor Source: [modules/mc_raptor](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/mc_raptor)