Skip to content

docs: refresh, refactor extractor - #2259

Merged
vooon merged 25 commits into
ros2from
docs-refresh
Aug 8, 2026
Merged

vooon merged 25 commits into
ros2from
docs-refresh

Conversation

@vooon

@vooon vooon commented Aug 7, 2026

Copy link
Copy Markdown
Member

No description provided.

vooon added 9 commits August 7, 2026 16:56
- sim_state: drop the topic list from the class brief; the generated
  Publishers section already lists each topic with a description.
- Separate section-marker // comments (e.g. "// publishers") from the
  //! entity description with a blank line, so the extractor no longer
  concatenates them into verbose descriptions like "publishers Publish
  DEBUG messages...".
- Regenerate docs.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Replace the regex-based plugin_doc_extract with a clang-tooling AST extractor
(RecursiveASTVisitor), fixing the regex approach's fragility (unresolved
symbols, comment mis-attribution, type/alias heuristics).

The extractor parses each plugin with the clang AST using compile_commands.json
(produced by the mavros build with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON, merged
for mavros + mavros_extras) and captures:

- create_publisher/subscription/service/client with resolved type and string
  topic, plus the QoS argument (named helper or inline chain, resolved through
  variables, deduplicated by canonical config).
- node_declare_and_watch_parameter, make_handler (MAVLink type from handler
  params, incl. base-class/derived types and raw MSG_ID handlers),
  send_message (incl. classes derived from a mavlink message), and
  message_filters::Subscriber fields.
- Merging: MissionBase-derived plugins (waypoint/geofence/rallypoint) and
  setpoint-mixin plugins inherit their MAVLink traffic.
- Multiline plugin class descriptions preserved.

The generator (plugin_doc_gen.py) now renders a QoS appendix (qos.md of
distinct profiles with stable anchors) and uses Jinja templates for the plugin
index and per-plugin pages. Per-entity QoS is a structured mapping, not a JSON
string. gendoc.sh drives the new pipeline (builds the extractor, ensures
compile_commands.json, generates index/markdown/qos/index pages).

The pre-existing regex extractor is left in the repo but is not wired up; the
AST extractor is the only path used by gendoc.sh.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Regenerate all plugin index.json, per-plugin markdown, the plugin index and
the new QoS appendix from the clang-tooling extractor. Compared to the regex
tool these fix unresolved symbols/type names, add per-entity QoS links, and
de-duplicate repeated MAVLink publications.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Remove the old regex-era Python markdown renderer (render_markdown,
_render_api_section and the unused ApiEntry.rendered_type) and the suppressed
compatibility CLI args (--collector, --compile-commands, --clang-arg,
--no-regex-fallback) that were left over from the regex extractor. gendoc.sh
now errors if no output mode is given.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Add COLCON_IGNORE so colcon does not treat tools/ as a cmake package. The
clang-tooling CMakeLists.txt requires LLVM/clang, which colcon (and CI) would
otherwise try to build and fail on.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Convert each package's RST changelog into markdown for the mkdocs site
(version headers, bullet items, RST inline links).

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Move the old historical release notes out of the top-level README into a
dedicated docs/history.md page, and add per-package changelogs (converted from
CHANGELOG.rst) under docs/changelog/ with an index page. Link the changelog from
the README and docs index.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
The python.flask.security.xss.audit.direct-use-of-jinja2 rule flags the offline
Jinja renderer used by render_plugin_index(). It is used only for generating
markdown docs, not for serving web HTML, so mark the Environment() and
template.render() calls with the same # nosemgrep comment used by the existing
per-plugin template renderer (which semgrep does not flag).

Also apply ruff format to convert_changelogs.py.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
vooon added 15 commits August 8, 2026 10:00
Give new visitors a clear picture of what MAVROS is and why they would use it:
a plain-language intro, a data-flow diagram, key features, a real quick-start
(install + launch + verify a topic), a package overview, and links to the docs,
plugin reference, API and changelog.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
- mavros: point the API docs link at readthedocs/plugin reference instead of
  the dead wiki.ros.org page; fix ROS1 roslaunch examples to ros2 launch; note
  that up-to-date install instructions live in the readthedocs guide.
- mavros_extras: link to the full plugin reference.
- libmavconn: link to the docs and API reference.
- mavros_msgs: add the missing README (message/service overview + API links).
- test_mavros: mark the ROS1-era SITL hand-tests as historical.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Add mavros_examples to the top-level README package table, the docs index
package overview and the changelog (converter + generated page), since it ships
beginner example scripts for ROS 2.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
The install instructions are maintained in the readthedocs installation guide;
point there instead of duplicating (and drifting) binary/source install steps in
the package README.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Trim whitespace on the Jinja for-loop in the plugin index template so table
rows are contiguous (previously each row was followed by a blank line, which
broke the markdown table).

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Fix the broken inline Pixhawk link, point the mavlink dependency at
mavlink.io instead of the dead wiki.ros.org page, drop unused link references
(catkin, shadow, boost, iss35, iss856) and upgrade http:// to https://.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Generate qos.md from a dedicated Jinja template with two explicit sections
(named standard profiles and inline profiles). Each profile gets a heading
with a stable anchor, a settings table (history/depth/reliability/durability/
deadline/lifespan/liveliness) derived from the known rclcpp defaults or parsed
from the inline QoS(...) chain, a link to the rclcpp API docs for standard
profiles, and a reverse 'Used by' list linking back to the plugin pages. Add a
link to the ROS 2 QoS documentation in the header.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Split the reverse 'Used by' list into std and extras groups, each sorted by
plugin name, so the appendix layout stays stable across regenerations.

Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
@vooon
vooon merged commit 9694a97 into ros2 Aug 8, 2026
6 checks passed
@vooon
vooon deleted the docs-refresh branch August 8, 2026 09:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant