From c2f872c558932a6d3c8b03497a28b05da92c1046 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Tue, 20 May 2025 15:34:20 +1000 Subject: [PATCH] docs: put RC modules into their own category (#24847) --- Tools/px4moduledoc/markdownout.py | 22 +++++++++++----------- Tools/px4moduledoc/srcparser.py | 4 ++-- src/drivers/rc/crsf_rc/CrsfRc.cpp | 1 + src/drivers/rc/dsm_rc/DsmRc.cpp | 1 + src/drivers/rc/ghst_rc/GhstRc.cpp | 1 + src/drivers/rc/sbus_rc/SbusRc.cpp | 1 + src/drivers/rc_input/RCInput.cpp | 1 + 7 files changed, 18 insertions(+), 13 deletions(-) diff --git a/Tools/px4moduledoc/markdownout.py b/Tools/px4moduledoc/markdownout.py index 469e031a63..783ee620b0 100644 --- a/Tools/px4moduledoc/markdownout.py +++ b/Tools/px4moduledoc/markdownout.py @@ -40,25 +40,25 @@ The generated files will be written to the `modules` directory. ## Categories """ for category in sorted(module_groups): - result += "- [%s](modules_%s.md)\n" % (category.capitalize(), category) + result += f"- [{category.capitalize()}](modules_{category}.md)\n" self._outputs['main'] = result for category in sorted(module_groups): - result = "# Modules Reference: %s\n" % category.capitalize() + result = f"# Modules Reference: {category.capitalize()}\n\n" subcategories = module_groups[category] + if len(subcategories) > 1: - result += 'Subcategories:\n' - for subcategory in subcategories: + result += 'Subcategories:\n\n' + for subcategory in sorted(subcategories): if subcategory == '': continue subcategory_label = subcategory.replace('_', ' ').title() subcategory_file_name = category+'_'+subcategory - result += '- [%s](modules_%s.md)\n' % (subcategory_label, subcategory_file_name) + result += f'- [{subcategory_label}](modules_{subcategory_file_name}.md)\n' # add a sub-page for the subcategory - result_subpage = '# Modules Reference: %s (%s)\n' % \ - (subcategory_label, category.capitalize()) + result_subpage = f'# Modules Reference: {subcategory_label} ({category.capitalize()})\n' result_subpage += self._ProcessModules(subcategories[subcategory]) self._outputs[subcategory_file_name] = result_subpage @@ -68,14 +68,14 @@ The generated files will be written to the `modules` directory. def _ProcessModules(self, module_list): result = '' for module in module_list: - result += "## %s\n" % module.name() - result += "Source: [%s](https://github.com/PX4/PX4-Autopilot/tree/main/src/%s)\n\n" % (module.scope(), module.scope()) + 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 += "%s\n" % doc + result += f"{doc}\n" usage_string = module.usage_string() if len(usage_string) > 0: - result += '\n### Usage\n```\n%s\n```\n' % (module.name(), usage_string) + result += f'### Usage {{#{module.name()}_usage}}\n\n```\n{usage_string}\n```\n' return result def Save(self, dirname): diff --git a/Tools/px4moduledoc/srcparser.py b/Tools/px4moduledoc/srcparser.py index 4937f67b7e..8b56e7bb08 100644 --- a/Tools/px4moduledoc/srcparser.py +++ b/Tools/px4moduledoc/srcparser.py @@ -12,11 +12,11 @@ class ModuleDocumentation(object): """ # If you add categories or subcategories, they also need to be added to the - # TOC in https://github.com/PX4/PX4-user_guide/blob/main/en/SUMMARY.md + # TOC in https://github.com/PX4/PX4-Autopilot/blob/main/docs/en/SUMMARY.md valid_categories = ['driver', 'estimator', 'controller', 'system', 'communication', 'command', 'template', 'simulation', 'autotune'] valid_subcategories = ['', 'camera', 'distance_sensor', 'imu', 'ins', 'airspeed_sensor', - 'magnetometer', 'baro', 'optical_flow', 'rpm_sensor', 'transponder'] + 'magnetometer', 'baro', 'optical_flow', 'radio_control','rpm_sensor', 'transponder'] max_line_length = 80 # wrap lines that are longer than this diff --git a/src/drivers/rc/crsf_rc/CrsfRc.cpp b/src/drivers/rc/crsf_rc/CrsfRc.cpp index 3ea6c0ac27..d7401f57ae 100644 --- a/src/drivers/rc/crsf_rc/CrsfRc.cpp +++ b/src/drivers/rc/crsf_rc/CrsfRc.cpp @@ -526,6 +526,7 @@ This module parses the CRSF RC uplink protocol and generates CRSF downlink telem )DESCR_STR"); PRINT_MODULE_USAGE_NAME("crsf_rc", "driver"); + PRINT_MODULE_USAGE_SUBCATEGORY("radio_control"); PRINT_MODULE_USAGE_COMMAND("start"); PRINT_MODULE_USAGE_PARAM_STRING('d', "/dev/ttyS3", "", "RC device", true); diff --git a/src/drivers/rc/dsm_rc/DsmRc.cpp b/src/drivers/rc/dsm_rc/DsmRc.cpp index f35bc4487f..b12fbfedcc 100644 --- a/src/drivers/rc/dsm_rc/DsmRc.cpp +++ b/src/drivers/rc/dsm_rc/DsmRc.cpp @@ -399,6 +399,7 @@ This module does Spektrum DSM RC input parsing. )DESCR_STR"); PRINT_MODULE_USAGE_NAME("dsm_rc", "driver"); + PRINT_MODULE_USAGE_SUBCATEGORY("radio_control"); PRINT_MODULE_USAGE_COMMAND("start"); PRINT_MODULE_USAGE_PARAM_STRING('d', "/dev/ttyS3", "", "RC device", true); diff --git a/src/drivers/rc/ghst_rc/GhstRc.cpp b/src/drivers/rc/ghst_rc/GhstRc.cpp index 1aa3c23e89..aa4525d64c 100644 --- a/src/drivers/rc/ghst_rc/GhstRc.cpp +++ b/src/drivers/rc/ghst_rc/GhstRc.cpp @@ -292,6 +292,7 @@ This module does Ghost (GHST) RC input parsing. )DESCR_STR"); PRINT_MODULE_USAGE_NAME("ghst_rc", "driver"); + PRINT_MODULE_USAGE_SUBCATEGORY("radio_control"); PRINT_MODULE_USAGE_COMMAND("start"); PRINT_MODULE_USAGE_PARAM_STRING('d', "/dev/ttyS3", "", "RC device", true); PRINT_MODULE_USAGE_DEFAULT_COMMANDS(); diff --git a/src/drivers/rc/sbus_rc/SbusRc.cpp b/src/drivers/rc/sbus_rc/SbusRc.cpp index 12d57da141..2ebdcfa207 100644 --- a/src/drivers/rc/sbus_rc/SbusRc.cpp +++ b/src/drivers/rc/sbus_rc/SbusRc.cpp @@ -302,6 +302,7 @@ This module does SBUS RC input parsing. )DESCR_STR"); PRINT_MODULE_USAGE_NAME("sbus_rc", "driver"); + PRINT_MODULE_USAGE_SUBCATEGORY("radio_control"); PRINT_MODULE_USAGE_COMMAND("start"); PRINT_MODULE_USAGE_PARAM_STRING('d', "/dev/ttyS3", "", "RC device", true); PRINT_MODULE_USAGE_DEFAULT_COMMANDS(); diff --git a/src/drivers/rc_input/RCInput.cpp b/src/drivers/rc_input/RCInput.cpp index a86ade0ad0..214853f647 100644 --- a/src/drivers/rc_input/RCInput.cpp +++ b/src/drivers/rc_input/RCInput.cpp @@ -1018,6 +1018,7 @@ This module does the RC input parsing and auto-selecting the method. Supported m )DESCR_STR"); PRINT_MODULE_USAGE_NAME("rc_input", "driver"); + PRINT_MODULE_USAGE_SUBCATEGORY("radio_control"); PRINT_MODULE_USAGE_COMMAND("start"); PRINT_MODULE_USAGE_PARAM_STRING('d', "/dev/ttyS3", "", "RC device", true);