mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-11-22 14:19:57 +08:00
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>
97 lines
3.8 KiB
Python
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)
|