Skip to content

Commit 469c1d6

Browse files
bburdabburda
committed
feat(docs): Add comprehensive Sphinx documentation infrastructure
Set up complete documentation system using Sphinx with sphinx-needs for requirements management and traceability. Documentation structure: - Requirements organized by category (core, data, diagnostics, execution, configuration, system) with 92 SOVD API requirements mapped to ROS 2 - Design documentation with PlantUML architecture diagrams - Verification section with test case traceability Infrastructure additions: - Sphinx configuration with RTD theme and custom CSS for DataTables - sphinx-needs for requirements tracking with custom need types (req, spec, impl, test) and verification links - sphinxcontrib-plantuml for architecture diagrams - sphinx-autobuild for live preview during development - VS Code tasks for building and serving docs - GitHub Actions workflow for automated docs deployment to GitHub Pages Dev environment: - Updated Dockerfile with graphviz and plantuml for diagram generation - Added Python documentation dependencies to dev container - Standalone pyproject.toml in docs/ for isolated doc builds All requirements include implementation notes mapping SOVD concepts to ROS 2 equivalents (nodes, topics, services, actions, parameters, etc).
1 parent 754bea6 commit 469c1d6

18 files changed

Lines changed: 1527 additions & 27 deletions

File tree

‎.devcontainer/Dockerfile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y \
3333
yq \
3434
ca-certificates \
3535
clang-format \
36+
graphviz \
37+
plantuml \
3638
&& locale-gen en_US.UTF-8 \
3739
&& rm -rf /var/lib/apt/lists/*
3840

@@ -67,6 +69,9 @@ RUN pip install --break-system-packages \
6769
pytest-rerunfailures \
6870
sphinx \
6971
sphinx-rtd-theme \
72+
sphinx-needs \
73+
sphinxcontrib-plantuml \
74+
sphinx-autobuild \
7075
myst-parser
7176

7277
# Install hadolint for Dockerfile linting

‎.github/workflows/docs.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- ".github/workflows/docs.yml"
9+
pull_request:
10+
branches: [main]
11+
paths:
12+
- "docs/**"
13+
- ".github/workflows/docs.yml"
14+
workflow_dispatch:
15+
16+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
17+
permissions:
18+
contents: read
19+
pages: write
20+
id-token: write
21+
22+
concurrency:
23+
group: "pages"
24+
cancel-in-progress: false
25+
26+
jobs:
27+
build-docs:
28+
runs-on: ubuntu-24.04
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
33+
- name: Set up Python
34+
uses: actions/setup-python@v5
35+
with:
36+
python-version: "3.12"
37+
cache: "pip"
38+
39+
- name: Install dependencies
40+
run: |
41+
sudo apt-get update
42+
sudo apt-get install -y graphviz plantuml
43+
pip install -e docs/.[dev]
44+
45+
- name: Check links
46+
working-directory: docs
47+
run: sphinx-build -b linkcheck . _build/linkcheck
48+
49+
- name: Build documentation
50+
working-directory: docs
51+
run: sphinx-build -b html . _build/html -W --keep-going
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: docs/_build/html
57+
58+
deploy-docs:
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
runs-on: ubuntu-24.04
63+
needs: build-docs
64+
if: github.ref == 'refs/heads/main'
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4
69+

‎.vscode/tasks.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"version": "2.0.0",
3+
"tasks": [
4+
{
5+
"label": "Docs: Build",
6+
"type": "shell",
7+
"command": "${workspaceFolder}/.venv/bin/sphinx-build",
8+
"args": [
9+
"-b",
10+
"html",
11+
"docs",
12+
"docs/_build/html"
13+
],
14+
"group": {
15+
"kind": "build",
16+
"isDefault": true
17+
},
18+
"problemMatcher": []
19+
},
20+
{
21+
"label": "Docs: Serve",
22+
"type": "shell",
23+
"command": "${workspaceFolder}/.venv/bin/sphinx-autobuild",
24+
"args": [
25+
"--host",
26+
"0.0.0.0",
27+
"--port",
28+
"8000",
29+
"docs",
30+
"docs/_build/html"
31+
],
32+
"isBackground": true,
33+
"problemMatcher": [],
34+
"presentation": {
35+
"reveal": "always",
36+
"panel": "dedicated"
37+
}
38+
}
39+
]
40+
}
41+

‎docs/README.md‎

Lines changed: 82 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,90 @@
1-
# ROS 2 Medkit Gateway - Architecture Documentation
1+
# Documentation Development Guide
22

3-
This directory contains design documentation for the ros2_medkit_gateway project.
3+
This directory contains the Sphinx-based documentation for the `ros2_medkit` project.
44

5-
## Architecture Diagram
5+
## Prerequisites
66

7-
The `architecture.puml` file contains a PlantUML class diagram showing the relationships between the main components of the gateway.
7+
* **Python 3.12+**
8+
* **PlantUML** and **Graphviz** (for generating diagrams)
89

9-
### Main Components
10+
### Installing System Dependencies (Ubuntu/Debian)
1011

11-
1. **GatewayNode** - The main ROS 2 node that orchestrates the system
12-
- Extends `rclcpp::Node`
13-
- Manages periodic discovery and cache refresh
14-
- Runs the REST server in a separate thread
15-
- Provides thread-safe access to the entity cache
12+
```bash
13+
sudo apt-get update
14+
sudo apt-get install -y graphviz plantuml
15+
```
1616

17-
2. **DiscoveryManager** - Discovers ROS 2 entities and maps them to the SOVD hierarchy
18-
- Discovers Areas from node namespaces
19-
- Discovers Components from nodes, topics, and services
20-
- Extracts the entity hierarchy from the ROS 2 graph
17+
## Setup
2118

22-
3. **RESTServer** - Provides the HTTP/REST API
23-
- Serves endpoints: `/health`, `/`, `/areas`, `/components`, `/areas/{area_id}/components`
24-
- Retrieves cached entities from the GatewayNode
25-
- Runs on configurable host and port
19+
It is recommended to use a virtual environment for building the documentation.
2620

27-
4. **Data Models** - Entity representations
28-
- `Area` - Physical or logical domain
29-
- `Component` - Hardware or software component
30-
- `EntityCache` - Thread-safe cache of discovered entities
31-
21+
1. Create a virtual environment:
22+
```bash
23+
python3 -m venv .venv
24+
source .venv/bin/activate
25+
```
26+
27+
2. Install Python dependencies:
28+
```bash
29+
pip install -e .[dev]
30+
```
31+
32+
## Building Documentation
33+
34+
To build the HTML documentation, run the following command from the `docs` directory:
35+
36+
```bash
37+
sphinx-build -b html . _build/html
38+
```
39+
40+
The generated HTML files will be located in `_build/html/index.html`.
41+
42+
## Live Preview (Development Mode)
43+
44+
For a better development experience, you can use `sphinx-autobuild` to automatically rebuild the documentation and refresh your browser when you make changes.
45+
46+
1. Ensure you are in the `docs` directory and your virtual environment is activated:
47+
48+
```bash
49+
# Assuming you are in the project root
50+
cd docs
51+
source .venv/bin/activate
52+
```
53+
54+
2. Run the auto-build server:
55+
56+
```bash
57+
sphinx-autobuild . _build/html --port 8000 --host 0.0.0.0
58+
```
59+
60+
Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
61+
62+
## Directory Structure
63+
64+
* `pyproject.toml`: Project configuration and dependencies.
65+
* `conf.py`: Sphinx configuration file.
66+
* `index.rst`: Main entry point for the documentation.
67+
* `requirements/`: Contains requirements specifications (split by category).
68+
* `design/`: Contains design documentation and PlantUML diagrams.
69+
* `_static/`: Custom static files (CSS, JS).
70+
* `_templates/`: Custom templates.
71+
72+
## Adding New Requirements
73+
74+
Requirements are managed using `sphinx-needs`. To add a new requirement:
75+
76+
1. Identify the appropriate file in `requirements/` (e.g., `core.rst`, `system.rst`).
77+
2. Add a new `.. req::` directive:
78+
79+
```rst
80+
.. req:: Requirement Title
81+
:id: REQ_CATEGORY_XXX
82+
:status: open
83+
:tags: P
84+
85+
Description of the requirement.
86+
```
87+
88+
## CI/CD
89+
90+
The documentation is automatically built and deployed to GitHub Pages via GitHub Actions. The workflow is defined in `.github/workflows/docs.yml`.

‎docs/_static/custom.css‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
/* Fix DataTables display in Sphinx RTD Theme */
2+
.dataTables_wrapper {
3+
width: 100%;
4+
overflow-x: auto;
5+
display: block;
6+
}
7+
8+
table.dataTable {
9+
width: 100% !important;
10+
margin: 0 auto;
11+
clear: both;
12+
border-collapse: collapse;
13+
border-spacing: 0;
14+
table-layout: auto;
15+
}
16+
17+
/* Ensure the table cells don't collapse too much */
18+
table.dataTable th,
19+
table.dataTable td {
20+
white-space: normal !important;
21+
word-wrap: break-word;
22+
vertical-align: top;
23+
}
24+
25+
/* Increase the content width to accommodate large tables */
26+
.wy-nav-content {
27+
max-width: 100% !important;
28+
}
29+
30+
/* Ensure the main container uses full width */
31+
.wy-grid-for-nav {
32+
width: 100%;
33+
max-width: 100%;
34+
}
35+
36+
/* Inspiration from Furo / Sphinx-Needs modern styling */
37+
:root {
38+
--sn-color-need-border: #e0e0e0;
39+
--sn-color-need-row-border: #f5f5f5;
40+
--sn-color-need-bg: #fafafa;
41+
--sn-color-need-bg-head: #f0f0f0;
42+
--sn-color-datatable-label: #666;
43+
--sn-color-datatable-btn-border: #ccc;
44+
}
45+
46+
/* Apply these variables to the DataTable if Sphinx-Needs uses them,
47+
or manually apply them to match the look */
48+
49+
table.dataTable thead th {
50+
background-color: #f0f0f0; /* Fallback */
51+
background-color: var(--sn-color-need-bg-head);
52+
border-bottom: 2px solid #e0e0e0;
53+
border-bottom: 2px solid var(--sn-color-need-border);
54+
color: #333;
55+
font-weight: bold;
56+
padding: 10px !important;
57+
}
58+
59+
table.dataTable tbody td {
60+
border-bottom: 1px solid #f5f5f5;
61+
border-bottom: 1px solid var(--sn-color-need-row-border);
62+
padding: 8px !important;
63+
}
64+
65+
table.dataTable.no-footer {
66+
border-bottom: 1px solid #e0e0e0;
67+
border-bottom: 1px solid var(--sn-color-need-border);
68+
}
69+
70+
/* Improve search/filter inputs in DataTables */
71+
.dataTables_filter input {
72+
border: 1px solid #ccc;
73+
border-radius: 4px;
74+
padding: 4px 8px;
75+
}
76+
77+
.dataTables_length select {
78+
border: 1px solid #ccc;
79+
border-radius: 4px;
80+
padding: 4px;
81+
}
82+

0 commit comments

Comments
 (0)