Skip to content

Commit df7027d

Browse files
rvxfahimrvxfahim
committed
Add Sphinx documentation workflow and initial documentation files
1 parent c316710 commit df7027d

File tree

10 files changed

+201
-113
lines changed

10 files changed

+201
-113
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Build and Deploy Sphinx Docs
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/docs.yml'
9+
- 'README.md'
10+
- 'ARCHITECTURE.md'
11+
- 'TESTING_GUIDE.md'
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
concurrency:
20+
group: 'pages'
21+
cancel-in-progress: true
22+
23+
jobs:
24+
build:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.x'
34+
35+
- name: Install documentation dependencies
36+
run: |
37+
python -m pip install --upgrade pip
38+
python -m pip install -r docs/requirements.txt
39+
40+
- name: Build Sphinx HTML
41+
run: |
42+
python -m sphinx -b html docs docs/_build/html
43+
# Ensure GitHub Pages doesn't try to run Jekyll so _static is served
44+
touch docs/_build/html/.nojekyll
45+
46+
- name: Upload artifact
47+
uses: actions/upload-pages-artifact@v3
48+
with:
49+
path: docs/_build/html
50+
51+
deploy:
52+
environment:
53+
name: github-pages
54+
url: ${{ steps.deployment.outputs.page_url }}
55+
runs-on: ubuntu-latest
56+
needs: build
57+
steps:
58+
- name: Deploy to GitHub Pages
59+
id: deployment
60+
uses: actions/deploy-pages@v4

‎REFACTOR_SUMMARY.md‎

Lines changed: 0 additions & 113 deletions
This file was deleted.

‎docs/api.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# API Reference (C/C++)
2+
3+
This project is primarily C/C++ embedded code. Sphinx's built-in autodoc targets Python, so for rich API documentation we recommend integrating Doxygen with the Breathe Sphinx extension.
4+
5+
## Planned enhancement
6+
7+
We will add a Doxygen + Breathe pipeline to extract C/C++ symbols and render them here. Outline:
8+
9+
1. Add a `Doxyfile` targeting `src/` and `lib/`.
10+
2. Generate XML output: `doxygen -g` then `doxygen`.
11+
3. Add Breathe to `docs/requirements.txt` (`breathe`), and update `docs/conf.py`:
12+
- `extensions += ["breathe"]`
13+
- `breathe_projects = {"CAN-Lecture": "_doxygen/xml"}`
14+
- `breathe_default_project = "CAN-Lecture"`
15+
4. Create reStructuredText or MyST pages with `breathe` directives (`doxygenindex`, `doxygennamespace`, `doxygenclass`, etc.).
16+
17+
Until then, refer to these source locations:
18+
19+
- CAN driver abstraction: `lib/CanDriver/`
20+
- Message router core: `src/common/MessageRouter.{h,cpp}`
21+
- RX CAN interface: `src/rx/CanInterface.{h,cpp}`
22+
- DBC wrapper include: `src/generated_lecture_dbc.c`

‎docs/architecture.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Architecture
2+
3+
```{include} ../ARCHITECTURE.md
4+
```

‎docs/can-and-dbc.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# CAN and DBC
2+
3+
This project uses a DBC-driven workflow to encode/decode CAN frames consistently across the RX and TX targets.
4+
5+
## Sources and generated code
6+
7+
- DBC source: `tools/Lecture.dbc`
8+
- Generated C wrapper (do not edit): `lib/Generated/lib/lecture.{c,h}`
9+
- Single include in the project: `src/generated_lecture_dbc.c` (pulls in the generated library)
10+
11+
Driver abstraction lives under `lib/CanDriver/` and supports the ESP32 internal CAN controller and common external controllers.
12+
13+
## Regenerating from DBC (Windows)
14+
15+
1. Ensure the DBC is saved at `tools/Lecture.dbc`.
16+
2. Run the generator (Windows only, provided in repo):
17+
18+
- Tool: `tools/c-coderdbc/build/coderdbc.exe`
19+
- Output folder (autodetected by script): `lib/Generated/` (subfolders are managed by the generator)
20+
21+
3. Commit the updated files under `lib/Generated/`.
22+
23+
The code should always use the generated types and pack/unpack helpers:
24+
25+
- Type: `Cluster_t`
26+
- Pack: `Pack_Cluster_lecture(...)`
27+
- Unpack: `Unpack_Cluster_lecture(...)`
28+
29+
## RX mailbox and topics
30+
31+
- RX config: mailbox filter listening to ID `0x65` via `CAN0.watchFor(0x65)`
32+
- Data flow: ISR → EventQueue → SystemController → MessageRouter → UI/IOModule
33+
- Router publishes `Cluster_t` with sticky last value and a millis() timestamp. Consumers subscribe to receive updates.
34+
35+
## TX specifics
36+
37+
- No LVGL; keep `CAN0.setDebuggingMode(true)` during development
38+
- Send `Cluster_t` using `Pack_Cluster_lecture` on each cycle
39+
40+
See also `ARCHITECTURE.md` for the broader system overview and `include/TFTConfiguration.h` for display configuration (RX only).

‎docs/conf.py‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import os
2+
from datetime import datetime
3+
4+
# -- Project information -----------------------------------------------------
5+
6+
project = "CAN Lecture RX/TX"
7+
author = "Project Contributors"
8+
current_year = datetime.now().year
9+
copyright = f"{current_year}, {author}"
10+
11+
# -- General configuration ---------------------------------------------------
12+
13+
extensions = [
14+
"myst_parser",
15+
"sphinx.ext.autosectionlabel",
16+
]
17+
18+
# MyST configuration to support GitHub-flavored Markdown conveniences
19+
myst_enable_extensions = [
20+
"colon_fence",
21+
"deflist",
22+
"html_image",
23+
"attrs_block",
24+
]
25+
26+
templates_path = ["_templates"]
27+
exclude_patterns = [
28+
"_build",
29+
"Thumbs.db",
30+
".DS_Store",
31+
]
32+
33+
# -- Options for HTML output -------------------------------------------------
34+
35+
html_theme = "furo"
36+
html_title = project
37+
html_static_path = ["_static"]
38+
39+
# Make section labels unique across files
40+
autosectionlabel_prefix_document = True

‎docs/getting-started.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Getting started
2+
3+
```{include} ../README.md
4+
:relative-docs: ../
5+
:relative-images:
6+
```

‎docs/index.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# CAN Lecture RX/TX Documentation
2+
3+
Welcome to the CAN Lecture RX/TX project documentation. This site covers how the project is structured, how to build and run it on the ESP32 boards, and how data flows through the system.
4+
5+
## Contents
6+
7+
```{toctree}
8+
:maxdepth: 2
9+
:caption: Project docs
10+
11+
getting-started
12+
architecture
13+
testing
14+
can-and-dbc
15+
api
16+
```
17+
18+
## Links
19+
20+
- Source repository: GitHub (same repository hosting these pages)
21+
- PlatformIO: https://platformio.org/
22+
- LVGL: https://lvgl.io/

‎docs/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx>=7.3
2+
furo>=2024.8.6
3+
myst-parser>=3.0.1

‎docs/testing.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Testing
2+
3+
```{include} ../TESTING_GUIDE.md
4+
```

0 commit comments

Comments
 (0)