[#156] Add docs for upcoming release 0.1 #157
Merged
+3,533
−313
Conversation
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
- Remove 'under construction' note from index.rst - Update manifest-discovery.rst API endpoints from 0.2.0 to 0.1.0
Add comprehensive server.rst documenting: - Network settings (host, port) - TLS/HTTPS configuration - CORS configuration - Data access settings - Performance tuning options
Add comprehensive REST API docs including: - All discovery, data, operations, configurations, faults endpoints - Authentication endpoints - Error response format and error codes - URL encoding conventions - SOVD compliance notes Reorganize API docs into rest.rst and cpp.rst
Add documentation for companion projects: - web-ui.rst: sovd_web_ui web interface quick start - mcp-server.rst: ros2_medkit_mcp LLM integration guide Both include Docker usage, configuration, and integration examples.
- Add explanation of SOVD entity hierarchy (Areas, Components, Apps, Functions) - Add note explaining discovery modes (runtime-only, hybrid, manifest-only) - Update Web UI section with Docker quick start - Add LLMs (MCP) section - Expand Next Steps with categorized links
Define key terms: Area, App, Component, Function, Configuration, Data, Discovery Mode, Entity, Execution, Fault, Gateway, Manifest, MCP, Operation, Resource Collection, Runtime Linking, SOVD, Synthetic Component
Document all features included in first public release: - Gateway with REST API and discovery modes - Fault manager with debounce lifecycle - Fault reporter client library - Diagnostic bridge - Serialization library - Message definitions - SOVD compliance status
Add screenshots to documentation: - 21 screenshots in docs/_static/images/ - Web UI tutorial with step-by-step visual guide - Getting started with API response screenshots Add demo tutorials: - demos/index.rst: Overview of available demos - demos/demo-sensor.rst: Built-in sensor demo walkthrough - demos/demo-turtlebot3.rst: TurtleBot3 simulation guide Fix trailing whitespace in glossary.rst
- Replace http:get/post/put/delete directives with standard RST - Fix broken glossary reference to fault-reporting design doc - Add note about running Doxygen separately for C++ API docs
- Add docs/api/messages.rst with Fault.msg, FaultEvent.msg, services - Add docs/config/fault-manager.rst with all FaultManager parameters - Add docs/config/diagnostic-bridge.rst for migration from diagnostics - Fix rosmsg lexer warnings (use text highlighting) - Fix broken fault-reporting references (point to design docs)
- Change 'Configurations' to 'Configuration' (singular) - Change 'Authentication' to 'Auth' to match actual tags in specs
Add missing category tabs: - Subscriptions - DataSets - Scripts - Modes - ClearData - Logs - CommLogs - BulkData - Lifecycle - Updates Now all requirement categories from specs/ are filterable in coverage report.
…utorial The following screenshots were incorrectly included in sensor demo: - 06_topic_data_view.png - 07_operations_panel.png - 08_operations_execution.png - 09_configurations_list.png - 10_configuration_edit.png - 18_faults_injected_dashboard.png - 19_faults_injected_app_view.png These screenshots show TurtleBot3 components and have been moved to demo-turtlebot3.rst in appropriate sections: - Reading Sensor Data (06) - Controlling the Robot (07, 08) - Managing Parameters (09, 10) - Working with Faults (18, 19) Sensor demo now only references its own screenshots: - 20_sensor_demo_run_terminal.png - 21_sensor_demo_ui_view.png
…ch_demos Major changes: - Replaced description of test demo_nodes with actual sensor_diagnostics demo - Updated to Docker-based deployment with run-demo.sh scripts - Added proper sensor descriptions: lidar_sim, camera_sim, imu_sim, gps_sim - Documented dual fault reporting paths (legacy diagnostics + modern direct) - Added fault injection scripts documentation - Included architecture diagram and comparison table - Set all screenshot widths to 600px (both sensor and turtlebot3 demos) The sensor demo now correctly describes the selfpatch_demos/sensor_diagnostics demo instead of the internal test nodes from ros2_medkit.
Added demo-quick-start.rst documenting built-in demo_nodes: - Fastest way to explore gateway without Docker - Automotive-style sensors (temp, RPM, brake pressure, door, LIDAR) - Actuators (brake, lights) and operations (calibration service/action) - LIDAR with intentional faults for testing fault management - Namespace-based area hierarchy (powertrain, chassis, body, perception) Updated demos/index.rst with progressive learning path: 1. Quick Start (< 1 min setup, local, no Docker) 2. Sensor Diagnostics (~5 min, Docker, fault injection) 3. TurtleBot3 (~10 min, Gazebo, full robot stack) Includes comparison table and 'Choose Your Demo' guide for users.
… tests exist Enhanced generate_verification.py script to automatically update requirement status from 'open' to 'verified' in spec files when tests are found that verify them. Changes: - Added update_requirement_status() function to scan and update spec files - Script now collects all verified REQ_* IDs from test annotations - Automatically updates :status: field in docs/requirements/specs/*.rst - Updated 36 requirements across 8 spec files Verified requirements by category: - Discovery: 9 requirements (REQ_INTEROP_001, 003-007, 009-011) - Data: 3 requirements (REQ_INTEROP_033-035) - Operations: 7 requirements (REQ_INTEROP_018-025) - Configurations: 5 requirements (REQ_INTEROP_048-052) - Faults: 5 requirements (REQ_INTEROP_036-039, 088) - Subscriptions: 1 requirement (REQ_INTEROP_012) - DataSets: 4 requirements (REQ_INTEROP_013-015, 037) - Auth: 2 requirements (REQ_INTEROP_086-087) Total: 158 tests verify 37 unique requirements.
- Update getting_started.rst with correct API response examples - Fix dual-path apps/components endpoint documentation - Add TODO comments in rest_server.cpp for dual-path bug - Simplify installation.rst prerequisites - Update demo-sensor.rst with fault injection examples - Refactor demo-turtlebot3.rst to match actual manifest structure - Remove redundant demo-quick-start.rst (covered in getting_started) - Simplify demos/index.rst by removing comparison table - Fix postman collection image filename typo - Verify troubleshooting.rst accuracy
Contributor
There was a problem hiding this comment.
Pull request overview
Updates documentation for the upcoming 0.1.0 release, adding new tutorials/reference pages and expanding requirements/traceability docs, with a few accompanying non-doc changes.
Changes:
- Added new tutorials (demos, Web UI, MCP server) and expanded “Getting Started”/index navigation.
- Added/reshaped API reference docs (REST, messages, C++ API) and updated requirements coverage/status pages.
- Updated the verification generator script and added small REST server commentary around a known route semantic issue.
Reviewed changes
Copilot reviewed 34 out of 56 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| src/ros2_medkit_gateway/src/http/rest_server.cpp | Adds TODO commentary about the component/app dual-path routing semantics. |
| scripts/generate_verification.py | Extends verification generation and adds requirement status auto-update behavior. |
| docs/tutorials/web-ui.rst | New tutorial for sovd_web_ui. |
| docs/tutorials/mcp-server.rst | New tutorial for ros2_medkit_mcp MCP server usage. |
| docs/tutorials/manifest-discovery.rst | Updates “Since” versions for manifest-mode endpoints. |
| docs/tutorials/index.rst | Adds demos + companion projects to tutorials index. |
| docs/tutorials/demos/index.rst | New demos landing page. |
| docs/tutorials/demos/demo-turtlebot3.rst | New TurtleBot3 demo walkthrough. |
| docs/tutorials/demos/demo-sensor.rst | New sensor diagnostics demo walkthrough. |
| docs/troubleshooting.rst | Updates troubleshooting guidance and tuning examples. |
| docs/requirements/specs/subscriptions.rst | Marks one subscription requirement as verified. |
| docs/requirements/specs/operations.rst | Marks multiple operations requirements as verified. |
| docs/requirements/specs/faults.rst | Marks multiple faults requirements as verified. |
| docs/requirements/specs/discovery.rst | Marks multiple discovery requirements as verified. |
| docs/requirements/specs/datasets.rst | Marks multiple datasets requirements as verified. |
| docs/requirements/specs/data.rst | Marks multiple data requirements as verified. |
| docs/requirements/specs/configuration.rst | Marks multiple configuration requirements as verified. |
| docs/requirements/specs/auth.rst | Marks auth requirements as verified. |
| docs/requirements/coverage.rst | Expands coverage tabs and aligns tag naming. |
| docs/pyproject.toml | Adds sphinx-copybutton dependency. |
| docs/installation.rst | Streamlines installation prerequisites and updates health response example. |
| docs/index.rst | Adds quick reference section and includes glossary/changelog in nav. |
| docs/glossary.rst | New glossary page. |
| docs/getting_started.rst | Expands walkthrough; switches examples toward /apps usage and adds checkpoints. |
| docs/config/server.rst | New server configuration reference. |
| docs/config/index.rst | Adds new config reference pages to the config index. |
| docs/config/fault-manager.rst | New fault manager configuration reference. |
| docs/config/diagnostic-bridge.rst | New diagnostic bridge configuration reference. |
| docs/conf.py | Enables sphinx_copybutton extension. |
| docs/changelog.rst | New changelog for 0.1.0. |
| docs/api/rest.rst | New REST API reference page. |
| docs/api/messages.rst | New ROS 2 messages/services reference page. |
| docs/api/index.rst | Reworks API index into REST/messages/C++ pages. |
| docs/api/cpp.rst | New Doxygen/Breathe C++ API reference page. |
| docs/_static/images/00_ui_view.png | Adds screenshot asset for docs. |
| docs/_static/images/01a_connection_dialog.png | Adds screenshot asset for docs. |
| docs/_static/images/01b_connection_dialog_filled.png | Adds screenshot asset for docs. |
| docs/_static/images/02_entity_tree_collapsed.png | Adds screenshot asset for docs. |
| docs/_static/images/03_entity_tree_expanded.png | Adds screenshot asset for docs. |
| docs/_static/images/04_app_entity_detail.png | Adds screenshot asset for docs. |
| docs/_static/images/05_data_view.png | Adds screenshot asset for docs. |
| docs/_static/images/06_topic_data_view.png | Adds screenshot asset for docs. |
| docs/_static/images/07_operations_panel.png | Adds screenshot asset for docs. |
| docs/_static/images/08_operations_execution.png | Adds screenshot asset for docs. |
| docs/_static/images/09_configurations_list.png | Adds screenshot asset for docs. |
| docs/_static/images/10_configuration_edit.png | Adds screenshot asset for docs. |
| docs/_static/images/12_curl_health.png | Adds screenshot asset for docs. |
| docs/_static/images/13_curl_areas_turtlebot3.png | Adds screenshot asset for docs. |
| docs/_static/images/14_curl_topic_odom.png | Adds screenshot asset for docs. |
| docs/_static/images/15_postman_collection.png | Adds screenshot asset for docs. |
| docs/_static/images/16_turtlebot_gazebo.png | Adds screenshot asset for docs. |
| docs/_static/images/17_turtlebot_run_demo_terminal.png | Adds screenshot asset for docs. |
| docs/_static/images/18_faults_injected_dashboard.png | Adds screenshot asset for docs. |
| docs/_static/images/19_faults_injected_app_view.png | Adds screenshot asset for docs. |
| docs/_static/images/20_sensor_demo_run_terminal.png | Adds screenshot asset for docs. |
| docs/_static/images/21_sensor_demo_ui_view.png | Adds screenshot asset for docs. |
Components are logical groupings (synthetic or manifest-defined), Apps are individual ROS 2 nodes. Fixed misleading statements that suggested components map directly to nodes.
Address user feedback: - Fix installation path: clone directly to src directory - Add demo nodes table with entity IDs and namespaces - Fix checkpoint message to match actual log output - Fix Discovery Modes table: Apps available in runtime-only mode - Fix Web UI port documentation (5173 dev vs 3000 Docker) - Add mkdir command before fault manager launch - Fix is_located_on vs component field consistency - Add x-medkit wrapper to REST API response examples Address PR #157 review comments: - Fix executable names in diagnostic-bridge.rst (fault_manager_node, diagnostic_bridge_node) - Fix config path reference in server.rst - Update /apps endpoint docs to clarify availability - Change action response status from 201 to 202 Accepted - Fix REQ_INTEROP_025 status to open (cyclic-subscriptions not implemented) - Remove incorrect @verifies REQ_INTEROP_025 from config tests - Update TODO comments with issue #158 reference - Fix generate_verification.py to scan req blocks properly - Fix configuration test @verifies tags to use REQ_INTEROP_048-052
bburda
force-pushed
the
docs/add-more-docs
branch
from
7bcf98f to
bd67e7c
Compare
mfaferek93
approved these changes
Feb 1, 2026
bburda
added a commit
that referenced
this pull request
Feb 1, 2026
Address user feedback: - Fix installation path: clone directly to src directory - Add demo nodes table with entity IDs and namespaces - Fix checkpoint message to match actual log output - Fix Discovery Modes table: Apps available in runtime-only mode - Fix Web UI port documentation (5173 dev vs 3000 Docker) - Add mkdir command before fault manager launch - Fix is_located_on vs component field consistency - Add x-medkit wrapper to REST API response examples Address PR #157 review comments: - Fix executable names in diagnostic-bridge.rst (fault_manager_node, diagnostic_bridge_node) - Fix config path reference in server.rst - Update /apps endpoint docs to clarify availability - Change action response status from 201 to 202 Accepted - Fix REQ_INTEROP_025 status to open (cyclic-subscriptions not implemented) - Remove incorrect @verifies REQ_INTEROP_025 from config tests - Update TODO comments with issue #158 reference - Fix generate_verification.py to scan req blocks properly - Fix configuration test @verifies tags to use REQ_INTEROP_048-052
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.
Pull Request
Summary
Updates documentation for the upcoming 0.1.0 release, adding new tutorials/reference pages and expanding requirements/traceability docs, with a few accompanying non-doc changes.
Changes:
Issue
Link the related issue (required):
Type
Testing
How was this tested / how should reviewers verify it?
Ran manually documentation commands.
Checklist