Skip to content

Commit 0e6f3db

Browse files
tore-espressiftore-espressif
committed
WIP docs: Add skeleton for GitHub Actions workflow to build docs
1 parent 63a4825 commit 0e6f3db

File tree

11 files changed

+327
-0
lines changed

11 files changed

+327
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
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+
58+
- name: Set up Python
59+
uses: actions/setup-python@v5
60+
with:
61+
python-version: '3.12'
62+
63+
- name: Install Python dependencies
64+
working-directory: docs
65+
run: |
66+
pip install -r requirements.txt
67+
68+
- name: Get git version
69+
id: git_version
70+
run: |
71+
git_ver=$(git describe --always)
72+
echo "version=$git_ver" >> $GITHUB_OUTPUT
73+
echo "GIT_VER=$git_ver" >> $GITHUB_ENV
74+
75+
- name: Set up SSH
76+
run: |
77+
mkdir -p ~/.ssh
78+
echo "${{ secrets.DOCS_PRIVATEKEY }}" > ~/.ssh/id_rsa
79+
chmod 600 ~/.ssh/id_rsa
80+
ssh-keyscan -H ${{ vars.DOCS_SERVER }} >> ~/.ssh/known_hosts || true
81+
82+
- name: Deploy documentation
83+
working-directory: docs
84+
env:
85+
GIT_VER: ${{ steps.git_version.outputs.version }}
86+
DOCS_BUILD_DIR: ${{ github.workspace }}/docs/_build
87+
DOCS_DEPLOY_URL_BASE: ${{ vars.DOCS_URL_BASE }}
88+
DOCS_DEPLOY_SERVER: ${{ vars.DOCS_SERVER }}
89+
DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }}
90+
DOCS_DEPLOY_PATH: ${{ vars.DOCS_PATH }}
91+
# TYPE is optional - only used for output formatting (shows "deploy" or "preview" in logs)
92+
#TYPE: ${{ github.ref_name == 'master' && 'deploy' || 'preview' }}
93+
run: |
94+
deploy-docs

‎docs/Doxyfile‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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)/device/esp_tinyusb/include/tinyusb.h
17+
18+
WARN_NO_PARAMDOC = YES
19+
20+
## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
21+
##
22+
ENABLE_PREPROCESSING = YES
23+
MACRO_EXPANSION = YES
24+
EXPAND_ONLY_PREDEF = YES
25+
PREDEFINED = \
26+
$(ENV_DOXYGEN_DEFINES)
27+
28+
## Do not complain about not having dot
29+
##
30+
HAVE_DOT = NO
31+
32+
## Generate XML that is required for Breathe
33+
##
34+
GENERATE_XML = YES
35+
XML_OUTPUT = xml
36+
37+
GENERATE_HTML = NO
38+
HAVE_DOT = NO
39+
GENERATE_LATEX = NO
40+
GENERATE_MAN = YES
41+
GENERATE_RTF = NO
42+
43+
## Skip distracting progress messages
44+
##
45+
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/build_docs.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/bin/bash
2+
# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
3+
#
4+
build-docs -l en --project-path .. -t esp32s2 esp32s3 esp32p4 esp32h4

‎docs/conf_common.py‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
#
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
"""
6+
Common configuration for ESP-USB documentation
7+
"""
8+
9+
from esp_docs.conf_docs import * # noqa: F403,F401
10+
11+
12+
extensions += [ # Needed as a trigger for running doxygen
13+
'esp_docs.esp_extensions.dummy_build_system',
14+
'esp_docs.esp_extensions.run_doxygen',
15+
]
16+
# Languages supported
17+
languages = ['en']
18+
19+
# Project targets (used as URL slugs)
20+
idf_targets = ['esp32s2', 'esp32s3', 'esp32p4', 'esp32h4']
21+
22+
# GitHub repository information
23+
github_repo = 'espressif/esp-usb'
24+
25+
# Initialize html_context if not already defined
26+
html_context = {}
27+
html_context['github_user'] = 'espressif'
28+
html_context['github_repo'] = 'esp-usb'
29+
30+
# Static files path
31+
html_static_path = ['../_static']
32+
33+
# Project slug for URL
34+
project_slug = 'esp-usb'
35+
36+
# Versions URL (relative to HTML root)
37+
versions_url = '_static/docs_version.js'
38+
39+
# PDF file prefix
40+
pdf_file_prefix = u'esp-usb'

‎docs/en/api-reference/index.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0
4+
5+
API Reference
6+
=============
7+
8+
This section contains the API reference documentation generated from the source code.
9+
10+
.. note::
11+
API documentation will be generated from header files using Doxygen.

‎docs/en/conf.py‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
# SPDX-License-Identifier: Apache-2.0
3+
# -*- coding: utf-8 -*-
4+
#
5+
# English Language RTD & Sphinx config file
6+
#
7+
# Uses ../conf_common.py for most non-language-specific settings.
8+
9+
# Importing conf_common adds all the non-language-specific
10+
# parts to this conf module
11+
12+
try:
13+
from conf_common import * # noqa: F403,F401
14+
except ImportError:
15+
import os
16+
import sys
17+
sys.path.insert(0, os.path.abspath('../'))
18+
from conf_common import * # noqa: F403,F401
19+
20+
# General information about the project.
21+
project = u'ESP-USB Programming Guide'
22+
copyright = u'2025 Espressif Systems (Shanghai) CO LTD'
23+
author = u'Espressif Systems'
24+
pdf_title = u'ESP-USB Programming Guide'
25+
26+
# The language for content autogenerated by Sphinx. Refer to documentation
27+
# for a list of supported languages.
28+
language = 'en'

‎docs/en/index.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0
4+
5+
ESP-USB Programming Guide
6+
==========================
7+
8+
Welcome to the ESP-USB Programming Guide.
9+
10+
.. toctree::
11+
:maxdepth: 2
12+
:caption: Contents:
13+
14+
introduction
15+
16+
.. toctree::
17+
:maxdepth: 1
18+
:caption: API Reference
19+
20+
api-reference/index

‎docs/en/introduction.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2+
..
3+
.. SPDX-License-Identifier: Apache-2.0
4+
5+
Introduction
6+
============
7+
8+
ESP-USB is a repository containing ESP-IDF USB host and device class drivers
9+
which have been separated and uploaded into IDF Component Manager.
10+
11+
This documentation will be expanded with detailed information about:
12+
13+
* USB Host Library
14+
* USB Device Drivers
15+
* USB Class Drivers (CDC, HID, MSC, UAC, UVC)
16+
* API Reference
17+
* Examples and Usage

0 commit comments

Comments
 (0)