Skip to content

Commit 57d9bb0

Browse files
tore-espressiftore-espressif
committed
docs: Sphinx documentation setup and deployment
1 parent c04db58 commit 57d9bb0

39 files changed

+512
-101
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
# Build preview documentation for pull requests
5+
pull_request:
6+
# Build and deploy documentation for master branch
7+
push:
8+
branches:
9+
- master
10+
11+
jobs:
12+
build-docs:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v5
16+
17+
- name: Set up Python
18+
uses: actions/setup-python@v5
19+
with:
20+
python-version: '3.12'
21+
22+
- name: Install system dependencies
23+
run: |
24+
sudo apt-get update
25+
sudo apt-get install -y doxygen graphviz
26+
27+
- name: Install Python dependencies
28+
working-directory: docs
29+
run: |
30+
pip install -r requirements.txt
31+
32+
- name: Build documentation
33+
working-directory: docs
34+
run: |
35+
chmod +x build_docs.sh
36+
./build_docs.sh
37+
38+
- name: Upload documentation artifacts
39+
uses: actions/upload-artifact@v4
40+
with:
41+
name: docs
42+
path: |
43+
docs/_build
44+
!docs/_build/.doctrees
45+
46+
deploy-docs:
47+
needs: build-docs
48+
runs-on: ubuntu-latest
49+
# Set Deploy environment for master branch, otherwise set Preview environment
50+
environment: ${{ github.ref_name == 'master' && 'esp-docs deploy' || 'esp-docs preview' }}
51+
steps:
52+
- uses: actions/checkout@v5
53+
54+
- uses: actions/download-artifact@v4
55+
with:
56+
name: docs
57+
path: docs/_build
58+
59+
- name: Set up Python
60+
uses: actions/setup-python@v5
61+
with:
62+
python-version: '3.12'
63+
64+
- name: Install Python dependencies
65+
working-directory: docs
66+
run: |
67+
pip install -r requirements.txt
68+
69+
- name: Get git version
70+
id: git_version
71+
run: |
72+
git_ver=$(git describe --always)
73+
echo "version=$git_ver" >> $GITHUB_OUTPUT
74+
echo "GIT_VER=$git_ver" >> $GITHUB_ENV
75+
76+
- name: Deploy documentation
77+
working-directory: docs
78+
shell: bash
79+
env:
80+
GIT_VER: ${{ steps.git_version.outputs.version }}
81+
DOCS_BUILD_DIR: ${{ github.workspace }}/docs/_build
82+
DOCS_DEPLOY_URL_BASE: ${{ vars.DOCS_URL_BASE }}
83+
DOCS_DEPLOY_SERVER: ${{ vars.DOCS_SERVER }}
84+
DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }}
85+
DOCS_DEPLOY_PATH: ${{ vars.DOCS_PATH }}
86+
DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PRIVATEKEY }}
87+
# TYPE is optional - only used for output formatting (shows "deploy" or "preview" in logs)
88+
TYPE: ${{ github.ref_name == 'master' && 'deploy' || 'preview' }}
89+
run: |
90+
source $GITHUB_WORKSPACE/docs/utils.sh
91+
add_doc_server_ssh_keys "$DOCS_DEPLOY_PRIVATEKEY" "$DOCS_DEPLOY_SERVER" "$DOCS_DEPLOY_SERVER_USER"
92+
deploy-docs

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,7 @@ sdkconfig.old
66
dependencies.lock
77
**/managed_components/**
88
.vscode/
9-
doxygen/
109
warnings.txt
10+
docs/_build/**
11+
**/TODO
12+
**/venv/**

‎docs/Doxyfile‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
#
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
# Doxygen configuration for ESP-USB API documentation
6+
7+
PROJECT_NAME = "ESP-USB"
8+
PROJECT_BRIEF = "ESP-IDF USB Host and Device Drivers"
9+
10+
## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
11+
## to automatically generate API reference list files header_file.inc
12+
## These files are placed in '_inc' directory
13+
## and used to include in API reference documentation
14+
INPUT = \
15+
$(PROJECT_PATH)/host/usb/include/usb/usb_host.h \
16+
$(PROJECT_PATH)/host/usb/include/usb/usb_helpers.h \
17+
$(PROJECT_PATH)/host/usb/include/usb/usb_types_stack.h \
18+
$(PROJECT_PATH)/host/usb/include/usb/usb_types_ch9.h \
19+
$(PROJECT_PATH)/host/usb/include/usb/usb_types_ch11.h \
20+
$(PROJECT_PATH)/device/esp_tinyusb/include/tinyusb.h
21+
22+
WARN_NO_PARAMDOC = YES
23+
24+
## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
25+
##
26+
ENABLE_PREPROCESSING = YES
27+
MACRO_EXPANSION = YES
28+
EXPAND_ONLY_PREDEF = YES
29+
PREDEFINED = \
30+
$(ENV_DOXYGEN_DEFINES) \
31+
__DOXYGEN__=1 \
32+
__attribute__(x)= \
33+
ESP_STATIC_ASSERT()=
34+
35+
## Do not complain about not having dot
36+
##
37+
HAVE_DOT = NO
38+
39+
## Generate XML that is required for Breathe
40+
##
41+
GENERATE_XML = YES
42+
XML_OUTPUT = xml
43+
44+
GENERATE_HTML = NO
45+
HAVE_DOT = NO
46+
GENERATE_LATEX = NO
47+
GENERATE_MAN = YES
48+
GENERATE_RTF = NO
49+
50+
## Skip distracting progress messages
51+
##
52+
QUIET = YES

‎docs/README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# ESP-USB Documentation
2+
3+
This folder contains the ESP-Docs scaffolding for ESP-USB documentation.
4+
5+
## Structure
6+
7+
- `conf_common.py` - Common configuration for all languages
8+
- `en/` - English documentation source files
9+
- `conf.py` - English-specific configuration
10+
- `index.rst` - Main documentation index
11+
- `_static/` - Static files (CSS, JS, images)
12+
- `docs_version.js` - Target and version selector configuration
13+
- `Doxyfile` - Doxygen configuration file
14+
- `requirements.txt` - Python dependencies for building documentation
15+
- `build_docs.sh` - Build script for documentation
16+
17+
## Building Documentation
18+
19+
### Prerequisites
20+
21+
1. **Python 3.7 or newer**
22+
2. **Doxygen** - Install via system package manager:
23+
- Ubuntu/Debian: `sudo apt-get install doxygen graphviz`
24+
- macOS: `brew install doxygen graphviz`
25+
- Windows: Download from [Doxygen website](https://www.doxygen.nl/download.html)
26+
27+
### Build Steps
28+
29+
To build the documentation locally:
30+
31+
```bash
32+
cd docs
33+
pip install -r requirements.txt
34+
./build_docs.sh
35+
```
36+
37+
The built documentation will be in `docs/_build/`.
38+
39+
## Adding Documentation Content
40+
41+
1. Add reStructuredText (`.rst`) files to `docs/en/`
42+
2. Update `docs/en/index.rst` to include new pages in the table of contents
43+
3. For API documentation, ensure header files are included in `Doxyfile` INPUT paths
44+
45+
## Existing Documentation
46+
47+
The following folders contain existing markdown documentation that can be migrated to reStructuredText format:
48+
49+
- `device/` - Device-related documentation
50+
- `host/` - Host-related documentation

‎docs/_static/docs_version.js‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
//
3+
// SPDX-License-Identifier: Apache-2.0
4+
5+
var DOCUMENTATION_VERSIONS = {
6+
DEFAULTS: { has_targets: true,
7+
supported_targets: [ "esp32s2", "esp32s3", "esp32p4", "esp32h4" ]
8+
},
9+
IDF_TARGETS: [
10+
{ text: "ESP32-S2", value: "esp32s2" },
11+
{ text: "ESP32-S3", value: "esp32s3" },
12+
{ text: "ESP32-P4", value: "esp32p4" },
13+
{ text: "ESP32-H4", value: "esp32h4" }
14+
]
15+
};

‎docs/_static/usb_device/ext_phy_schematic_stusb03e.png‎

49.2 KB
Loading

‎docs/_static/usb_device/usb-board-connection.png‎

91.9 KB
Loading

‎docs/_static/usb_device/usb_fs_phy_sp5301.png‎

124 KB
Loading

‎docs/_static/usb_device/usb_vbus_voltage_monitor.png‎

5.4 KB
Loading

‎docs/_static/usb_host/dwc-otg-operation.png‎

60.6 KB
Loading

0 commit comments

Comments
 (0)