Files
PX4-Autopilot/Tools/px4moduledoc/markdownout.py
T
Alex E 59fa7a4a7d 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 <aelejandro9@gmail.com>
2026-11-10 08:51:33 +11:00

97 lines
3.8 KiB
Python

#! /usr/bin/env python3
"""
Class to generate Markdown documentation pages from parsed module doc strings
"""
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):
self._outputs = {}
result = """
# Modules & Commands Reference
The following pages document the PX4 modules, drivers and commands.
They describe the provided functionality, high-level implementation overview and how
to use the command-line interface.
::: info
**This is auto-generated from the source code** and contains the most recent modules documentation.
:::
It is not a complete list and NuttX provides some additional commands
as well (such as `free`). Use `help` on the console to get a list of all
available commands, and in most cases `command help` will print the usage.
Since this is generated from source, errors must be reported/fixed
in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) repository.
The documentation pages can be generated by running the following command from
the root of the PX4-Autopilot directory:
```
make module_documentation
```
The generated files will be written to the `modules` directory.
## Categories
"""
for category in sorted(module_groups):
result += f"- [{category.capitalize()}](modules_{category}.md)\n"
self._outputs['main'] = result
for category in sorted(module_groups):
result = f"# Modules Reference: {category.capitalize()}\n"
result += AUTOGEN_NOTE + '\n'
subcategories = module_groups[category]
if len(subcategories) > 1:
result += 'Subcategories:\n\n'
for subcategory in sorted(subcategories):
if subcategory == '':
continue
subcategory_label = subcategory.replace('_', ' ').title()
subcategory_file_name = category+'_'+subcategory
result += f'- [{subcategory_label}](modules_{subcategory_file_name}.md)\n'
# 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
result += '\n' + self._ProcessModules(subcategories[''])
self._outputs[category] = result
def _ProcessModules(self, module_list):
result = ''
for module in module_list:
result += f"\n## {module.name()}\n\n"
result += f"Source: [{module.scope()}](https://github.com/PX4/PX4-Autopilot/tree/main/src/{module.scope()})\n\n"
doc = module.documentation()
if len(doc) > 0:
result += f"{doc}\n"
usage_string = module.usage_string()
if len(usage_string) > 0:
result += f'### Usage {{#{module.name()}_usage}}\n\n```\n{usage_string}\n```\n'
return result
def Save(self, dirname):
for output_name in self._outputs:
output = self._outputs[output_name]
with codecs.open(os.path.join(dirname, 'modules_'+output_name+'.md'), 'w', 'utf-8') as f:
f.write(output)