Repository navigation
docs: refresh, refactor extractor - #2259
Merged
Merged
Conversation
- 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>
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>
This reverts commit 49d4adf.
Signed-off-by: Vladimir Ermakov <vooon341@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.