WIP docs: Add skeleton for GitHub Actions workflow to build docs

.github/workflows/docs.yml

@@ -0,0 +1,92 @@
+name: Build and Deploy Documentation
+
+on:
+  # Build preview documentation for pull requests
+  pull_request:
+  # Build and deploy documentation for master branch
+  push:
+    branches:
+      - master
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+
+      - name: Install Python dependencies
+        working-directory: docs
+        run: |
+          pip install -r requirements.txt
+
+      - name: Build documentation
+        working-directory: docs
+        run: |
+          chmod +x build_docs.sh
+          ./build_docs.sh
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: |
+            docs/_build
+            !docs/_build/.doctrees
+
+  deploy-docs:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    # Set Deploy environment for master branch, otherwise set Preview environment
+    environment: ${{ github.ref_name == 'master' && 'esp-docs deploy' || 'esp-docs preview' }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: docs/_build
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Python dependencies
+        working-directory: docs
+        run: |
+          pip install -r requirements.txt
+
+      - name: Get git version
+        id: git_version
+        run: |
+          git_ver=$(git describe --always)
+          echo "version=$git_ver" >> $GITHUB_OUTPUT
+          echo "GIT_VER=$git_ver" >> $GITHUB_ENV
+
+      - name: Deploy documentation
+        working-directory: docs
+        shell: bash
+        env:
+          GIT_VER: ${{ steps.git_version.outputs.version }}
+          DOCS_BUILD_DIR: ${{ github.workspace }}/docs/_build
+          DOCS_DEPLOY_URL_BASE: ${{ vars.DOCS_URL_BASE }}
+          DOCS_DEPLOY_SERVER: ${{ vars.DOCS_SERVER }}
+          DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }}
+          DOCS_DEPLOY_PATH: ${{ vars.DOCS_PATH }}
+          DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PRIVATEKEY }}
+          # TYPE is optional - only used for output formatting (shows "deploy" or "preview" in logs)
+          TYPE: ${{ github.ref_name == 'master' && 'deploy' || 'preview' }}
+        run: |
+          source $GITHUB_WORKSPACE/docs/utils.sh
+          add_doc_server_ssh_keys "$DOCS_DEPLOY_PRIVATEKEY" "$DOCS_DEPLOY_SERVER" "$DOCS_DEPLOY_SERVER_USER"
+          deploy-docs

.gitignore

@@ -6,5 +6,5 @@ sdkconfig.old
 dependencies.lock
 **/managed_components/**
 .vscode/
-doxygen/
 warnings.txt
+docs/_build/**

docs/Doxyfile

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Doxygen configuration for ESP-USB API documentation
+
+PROJECT_NAME           = "ESP-USB"
+PROJECT_BRIEF          = "ESP-IDF USB Host and Device Drivers"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files header_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+INPUT                  = \
+    $(PROJECT_PATH)/host/usb/include/usb/usb_host.h \
+    $(PROJECT_PATH)/device/esp_tinyusb/include/tinyusb.h
+
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES)
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
+
+## Skip distracting progress messages
+##
+QUIET = YES

docs/README.md

@@ -0,0 +1,50 @@
+# ESP-USB Documentation
+
+This folder contains the ESP-Docs scaffolding for ESP-USB documentation.
+
+## Structure
+
+- `conf_common.py` - Common configuration for all languages
+- `en/` - English documentation source files
+  - `conf.py` - English-specific configuration
+  - `index.rst` - Main documentation index
+- `_static/` - Static files (CSS, JS, images)
+  - `docs_version.js` - Target and version selector configuration
+- `Doxyfile` - Doxygen configuration file
+- `requirements.txt` - Python dependencies for building documentation
+- `build_docs.sh` - Build script for documentation
+
+## Building Documentation
+
+### Prerequisites
+
+1. **Python 3.7 or newer**
+2. **Doxygen** - Install via system package manager:
+   - Ubuntu/Debian: `sudo apt-get install doxygen graphviz`
+   - macOS: `brew install doxygen graphviz`
+   - Windows: Download from [Doxygen website](https://www.doxygen.nl/download.html)
+
+### Build Steps
+
+To build the documentation locally:
+
+```bash
+cd docs
+pip install -r requirements.txt
+./build_docs.sh
+```
+
+The built documentation will be in `docs/_build/`.
+
+## Adding Documentation Content
+
+1. Add reStructuredText (`.rst`) files to `docs/en/`
+2. Update `docs/en/index.rst` to include new pages in the table of contents
+3. For API documentation, ensure header files are included in `Doxyfile` INPUT paths
+
+## Existing Documentation
+
+The following folders contain existing markdown documentation that can be migrated to reStructuredText format:
+
+- `device/` - Device-related documentation
+- `host/` - Host-related documentation

docs/_static/docs_version.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+//
+// SPDX-License-Identifier: Apache-2.0
+
+var DOCUMENTATION_VERSIONS = {
+    DEFAULTS: { has_targets: true,
+                supported_targets: [ "esp32s2", "esp32s3", "esp32p4", "esp32h4" ]
+              },
+      IDF_TARGETS: [
+        { text: "ESP32-S2", value: "esp32s2" },
+        { text: "ESP32-S3", value: "esp32s3" },
+        { text: "ESP32-P4", value: "esp32p4" },
+        { text: "ESP32-H4", value: "esp32h4" }
+      ]
+};

docs/build_docs.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+#
+build-docs -l en --project-path .. -t esp32s2 esp32s3 esp32p4 esp32h4

docs/conf_common.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Common configuration for ESP-USB documentation
+"""
+
+from esp_docs.conf_docs import *  # noqa: F403,F401
+
+
+extensions += [  # Needed as a trigger for running doxygen
+               'esp_docs.esp_extensions.dummy_build_system',
+               'esp_docs.esp_extensions.run_doxygen',
+               ]
+# Languages supported
+languages = ['en']
+
+# Project targets (used as URL slugs)
+idf_targets = ['esp32s2', 'esp32s3', 'esp32p4', 'esp32h4']
+
+# GitHub repository information
+github_repo = 'espressif/esp-usb'
+
+# Initialize html_context if not already defined
+html_context = {}
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-usb'
+
+# Static files path
+html_static_path = ['../_static']
+
+# Project slug for URL
+project_slug = 'esp-usb'
+
+# Versions URL (relative to HTML root)
+versions_url = '_static/docs_version.js'
+
+# PDF file prefix
+pdf_file_prefix = u'esp-usb'

docs/en/api-reference/index.rst

@@ -0,0 +1,11 @@
+.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+..
+.. SPDX-License-Identifier: Apache-2.0
+
+API Reference
+=============
+
+This section contains the API reference documentation generated from the source code.
+
+.. note::
+   API documentation will be generated from header files using Doxygen.

docs/en/conf.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'ESP-USB Programming Guide'
+copyright = u'2025 Espressif Systems (Shanghai) CO LTD'
+author = u'Espressif Systems'
+pdf_title = u'ESP-USB Programming Guide'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

docs/en/index.rst

@@ -0,0 +1,20 @@
+.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+..
+.. SPDX-License-Identifier: Apache-2.0
+
+ESP-USB Programming Guide
+==========================
+
+Welcome to the ESP-USB Programming Guide.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference
+
+   api-reference/index

docs/en/introduction.rst

@@ -0,0 +1,17 @@
+.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+..
+.. SPDX-License-Identifier: Apache-2.0
+
+Introduction
+============
+
+ESP-USB is a repository containing ESP-IDF USB host and device class drivers
+which have been separated and uploaded into IDF Component Manager.
+
+This documentation will be expanded with detailed information about:
+
+* USB Host Library
+* USB Device Drivers
+* USB Class Drivers (CDC, HID, MSC, UAC, UVC)
+* API Reference
+* Examples and Usage

docs/requirements.txt

@@ -0,0 +1,3 @@
+esp-docs>=2.0.0
+sphinx>=5.0.0
+breathe>=4.35.0

docs/utils.sh

@@ -0,0 +1,18 @@
+# Bash helper functions for adding SSH keys
+
+function add_ssh_keys() {
+  local key_string="${1}"
+  mkdir -p ~/.ssh
+  chmod 700 ~/.ssh
+  echo -n "${key_string}" >~/.ssh/id_rsa_base64
+  base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa
+  chmod 600 ~/.ssh/id_rsa
+}
+
+function add_doc_server_ssh_keys() {
+  local key_string="${1}"
+  local server_url="${2}"
+  local server_user="${3}"
+  add_ssh_keys "${key_string}"
+  echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config
+}