feat(docs): restructure requirements and automate verification traceability

- Restructure documentation layout:
  - Move requirement specifications to `docs/requirements/specs/`
  - Add `introduction.rst` and update indices
  - Move design assets to `src/ros2_medkit_gateway/design/`

- Implement automated verification reporting:
  - Add `scripts/generate_verification.py` to scan C++ and Python tests for `@verifies` tags
  - Generate `docs/requirements/verification.rst` automatically during build
  - Add `docs/requirements/coverage.rst` with coverage statistics and matrices
  - Configure `sphinx-needs` for bidirectional traceability

- Update CI/CD:
  - Add verification generation step to `docs.yml` workflow
  - Update `.gitignore` to exclude generated documentation artifacts

- Traceability:
  - Annotate `test_gateway_node.cpp` and `test_integration.test.py` with requirement IDs
  - Update `docs/README.md` with usage instructions for the new workflow

Author: bburda

.github/workflows/docs.yml

@@ -42,6 +42,9 @@ jobs:
                   sudo apt-get install -y graphviz plantuml
                   pip install -e docs/.[dev]
 
+            - name: Generate verification report
+              run: python3 scripts/generate_verification.py
+
             - name: Check links
               working-directory: docs
               run: sphinx-build -b linkcheck . _build/linkcheck
@@ -66,4 +69,3 @@ jobs:
             - name: Deploy to GitHub Pages
               id: deployment
               uses: actions/deploy-pages@v4
-

.gitignore

@@ -107,6 +107,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/requirements/verification.rst
 
 # PyBuilder
 .pybuilder/

docs/README.md

@@ -85,6 +85,48 @@ Requirements are managed using `sphinx-needs`. To add a new requirement:
        Description of the requirement.
     ```
 
+## Traceability and Testing
+
+We use a bidirectional traceability approach to link Requirements to Tests and Code.
+
+### 1. Link Code to Test Case
+
+In your test code (C++ or Python), add comments to indicate which Requirement ID is being verified. The `generate_verification.py` script will automatically scan these tags and generate the `verification.rst` file.
+
+**Supported Tags:**
+*   `@verifies REQ_ID_1, REQ_ID_2` (Preferred)
+*   `Links to: REQ_ID` (Legacy)
+*   `Verifies: REQ_ID` (Legacy)
+
+#### C++ Example (`.cpp`)
+
+```cpp
+TEST_F(TestGatewayNode, test_health_endpoint) {
+  // @verifies REQ_SOVD_001
+  auto node = std::make_shared<GatewayNode>();
+  // ...
+}
+```
+
+#### Python Example (`.py`)
+
+```python
+def test_root_endpoint(self):
+    """
+    Test GET / returns gateway status and version.
+
+    @verifies REQ_SOVD_010
+    """
+    data = self._get_json('/')
+```
+
+This establishes the chain: **Requirement** <-> **Test Implementation (Code)** <-> **Verification Report**.
+
+**Note:** Only tests that verify at least one requirement will be included in the generated report.
+
 ## CI/CD
 
 The documentation is automatically built and deployed to GitHub Pages via GitHub Actions. The workflow is defined in `.github/workflows/docs.yml`.
+
+The `verification.rst` file is automatically generated during the CI build process, ensuring that the documentation always reflects the current state of the code.
+

docs/conf.py

@@ -3,12 +3,30 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+# Ensure readable plots
+matplotlib.rcParams["figure.facecolor"] = "white"
+matplotlib.rcParams["text.color"] = "black"
+matplotlib.rcParams["legend.frameon"] = True
+matplotlib.rcParams["legend.framealpha"] = 0.8
+matplotlib.rcParams["legend.facecolor"] = "white"
+matplotlib.rcParams["legend.edgecolor"] = "gray"
+matplotlib.rcParams["figure.autolayout"] = True
+matplotlib.rcParams["figure.figsize"] = [10, 6]
+matplotlib.rcParams["savefig.bbox"] = "tight"
+
+from datetime import datetime
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "ros2_medkit"
-copyright = "2025, selfpatch"
-author = "bburda"
+project_copyright = f"{datetime.now().year}, selfpatch"
+author = "selfpatch Team"
 
 version = "0.1.0"
 release = "0.1.0"
@@ -19,14 +37,27 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
     "sphinx_needs",
     "sphinxcontrib.plantuml",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# The suffix(es) of source filenames
+source_suffix = {
+    ".rst": "restructuredtext",
+}
+
+# The master toctree document
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx
+language = "en"
+
 # -- Options for Sphinx-Needs ------------------------------------------------
+needs_build_json = True
 needs_types = [
     dict(
         directive="req",
@@ -73,15 +104,30 @@
     },
 ]
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
+html_title = f"{project} Documentation"
 
+html_theme_options = {
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": False,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+# -- Options for intersphinx extension ---------------------------------------
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+}
 
 # -- Options for PlantUML ----------------------------------------------------
 plantuml = "java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar"
-
+plantuml_output_format = "svg"

docs/design/index.rst

@@ -1,37 +1,10 @@
 Architecture
 ============
 
-This section contains design documentation for the ros2_medkit_gateway project.
+This section contains design documentation for the ros2_medkit project packages.
 
-Architecture Diagram
---------------------
+.. toctree::
+   :maxdepth: 1
 
-The following diagram shows the relationships between the main components of the gateway.
-
-.. uml:: architecture.puml
-   :caption: ROS 2 Medkit Gateway Class Architecture
-
-Main Components
----------------
-
-1. **GatewayNode** - The main ROS 2 node that orchestrates the system
-   - Extends ``rclcpp::Node``
-   - Manages periodic discovery and cache refresh
-   - Runs the REST server in a separate thread
-   - Provides thread-safe access to the entity cache
-
-2. **DiscoveryManager** - Discovers ROS 2 entities and maps them to the SOVD hierarchy
-   - Discovers Areas from node namespaces
-   - Discovers Components from nodes, topics, and services
-   - Extracts the entity hierarchy from the ROS 2 graph
-
-3. **RESTServer** - Provides the HTTP/REST API
-   - Serves endpoints: ``/health``, ``/``, ``/areas``, ``/components``, ``/areas/{area_id}/components``
-   - Retrieves cached entities from the GatewayNode
-   - Runs on configurable host and port
-
-4. **Data Models** - Entity representations
-   - ``Area`` - Physical or logical domain
-   - ``Component`` - Hardware or software component
-   - ``EntityCache`` - Thread-safe cache of discovered entities
+   ros2_medkit_gateway/index
 

docs/design/ros2_medkit_gateway

@@ -0,0 +1 @@
+../../src/ros2_medkit_gateway/design

docs/index.rst

@@ -6,16 +6,18 @@
 ros2_medkit documentation
 =========================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
-
+Welcome to the documentation for **ros2_medkit**.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: General
 
-   requirements/index
+   introduction
    design/index
-   verification
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Requirements Engineering
+
+   requirements/index
 

docs/introduction.rst

@@ -0,0 +1,39 @@
+Introduction
+============
+
+ros2_medkit
+-----------
+
+Modern, SOVD-compatible diagnostics for ROS 2 robots, built around an entity tree
+(Area / Component / Function / App) for runtime discovery, health modeling, and troubleshooting.
+
+What is ros2_medkit?
+--------------------
+
+ros2_medkit is an experiment in **modern diagnostics for ROS 2–based systems**.
+
+Instead of hardcoding knowledge about every node, topic, or ECU, ros2_medkit models a robot
+as a **diagnostic entity tree**:
+
+- **Area** – physical or logical domain (e.g. ``base``, ``arm``, ``safety``, ``navigation``)
+- **Component** – hardware or software component within an area
+- **Function** – capability provided by one or more components
+- **App** – deployable software unit (node, container, process)
+
+The goal is to make this tree **compatible with the SOVD (Service-Oriented Vehicle Diagnostics) model**,
+so the same concepts can be used across robots, vehicles, and other embedded systems.
+
+Status
+------
+
+**Early prototype / work in progress**
+
+This is a personal open source project to explore diagnostic patterns for ROS 2.
+APIs, architecture, and naming may change at any time.
+
+Target Use Cases
+----------------
+
+- Runtime discovery of what is actually running on the robot
+- Health state modeled per Area / Component / Function / App
+- Better remote troubleshooting and fleet-level observability for ROS 2 robots

docs/pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
     "sphinx-needs>=1.0",
     "sphinx-rtd-theme",
     "sphinxcontrib-plantuml",
+    "matplotlib",
 ]
 
 [project.optional-dependencies]