finger563 · Nov 6, 2026 · Nov 6, 2026
diff --git a/doc/README.md b/doc/README.md
@@ -13,3 +13,22 @@ For more information please see [ESP Docs](https://github.com/espressif/esp-docs
 1. To ensure you can build the documentation, create a docker image for building the documentation  `docker build -t esp-docs .` (from within this directory) or `docker build -t esp-docs doc` from within the top-level project / espp directory.
 
 2. To build the documentation, simply run `./build_docs.sh` from within the top-level project / espp directory.
+
+## Building locally without Docker
+
+The same toolchain CI uses runs natively: Doxygen, Graphviz and (for the PDF)
+a TeX distribution plus pandoc, and the Python requirements in a virtual
+environment.
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r doc/requirements.txt
+cd doc
+build-docs -bs html -t esp32 -l en --project-path ../ --source-dir ./ --doxyfile_dir ./
+python3 -m http.server --directory _build/en/esp32/html 8000   # http://localhost:8000/
+```
+
+`build-docs` exits non-zero when the Sphinx warnings differ from
+`sphinx-known-warnings.txt`; the HTML is still complete in `_build/en/esp32/html`.
+The theme is `pydata-sphinx-theme` (see `conf_common.py`); esp-docs still runs
+Doxygen and provides the API directives.
diff --git a/doc/conf_common.py b/doc/conf_common.py
@@ -1,4 +1,5 @@
 from esp_docs.conf_docs import *  # noqa: F403,F401
+from esp_docs.conf_docs import setup as _esp_docs_setup
 
 extensions += ['sphinx_copybutton',
                # Needed as a trigger for running doxygen
@@ -18,13 +19,81 @@
 # link roles config
 github_repo = 'esp-cpp/espp'
 
-# context used by sphinx_idf_theme
+# --- theme -------------------------------------------------------------------
+# pydata-sphinx-theme instead of esp-docs' sphinx_idf_theme: a top bar, the
+# section navigation on the left, the page outline on the right, light and dark
+# modes, a version switcher driven by a JSON file we host (wired up by the
+# versioned-publishing workflow), and no chip selector or ESP-IDF version list.
+# esp-docs still runs Doxygen and provides the API directives; only the look
+# changes.
+html_theme = 'pydata_sphinx_theme'
+# esp-docs loads its theme as an extension too, and that extension's page hook
+# demands the chip and language selectors' config; neither is wanted here
+extensions = [ext for ext in extensions if ext != 'sphinx_idf_theme']
+html_static_path = ['_static']
+html_css_files = ['espp.css']
+html_title = 'espp'
+html_favicon = '_static/favicon.png'
+
+# the "edit this page" button and the GitHub link
 html_context['github_user'] = 'esp-cpp'
 html_context['github_repo'] = 'espp'
+html_context['github_version'] = 'main'
+html_context['doc_path'] = 'doc/en'
+
+html_theme_options = {
+    'logo': {
+        'text': 'espp',
+        'image_light': '_static/espp-logo.png',
+        'image_dark': '_static/espp-logo.png',
+    },
+    'github_url': 'https://github.com/esp-cpp/espp',
+    'icon_links': [
+        {
+            'name': 'Discord',
+            'url': 'https://discord.gg/dvcQw37xAY',
+            'icon': 'fa-brands fa-discord',
+        },
+    ],
+    'use_edit_page_button': True,
+    'navbar_align': 'left',
+    'header_links_before_dropdown': 5,
+    'show_toc_level': 2,
+    'navigation_with_keys': False,
+    'show_prev_next': True,
+    'secondary_sidebar_items': ['page-toc', 'edit-this-page'],
+    'footer_start': ['copyright'],
+    'footer_end': ['sphinx-version', 'theme-version'],
+    'pygments_light_style': 'default',
+    'pygments_dark_style': 'monokai',
+    # filled in by the publishing workflow (versioned docs): the JSON lists
+    # "latest" (main) and one entry per release/v* branch
+    # 'switcher': {'json_url': 'https://esp-cpp.github.io/espp/versions.json',
+    #              'version_match': version_match},
+}
+
+
+def _espp_html(app, config):
+    # esp-docs' own config-inited hook (setup_html) points html_logo at the
+    # Espressif logo; this runs after it (higher priority number) and gives the
+    # theme ours instead (the theme takes the logo from html_theme_options).
+    config.html_logo = None
 
-# Extra options required by sphinx_idf_theme
-project_slug = 'esp-cpp'
-versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js'
 
-idf_targets = ['esp32', 'esp32s2', 'esp32c3']
-languages = ['en']
+def setup(app):
+    # esp-docs' setup registers its Doxygen / API extensions and hooks; keep all
+    # of that, then add the hook above behind them.
+    ret = _esp_docs_setup(app)
+    # Config values the dropped theme extension used to register, which
+    # esp-docs' LaTeX and html-zip extensions still read (project_slug,
+    # html_zip ...). A conf.py setup runs after every extension's, so these
+    # exist before the config-inited handlers that read them.
+    for name, default in [('project_slug', 'espp'), ('versions_url', ''), ('project_homepage', ''),
+                          ('languages', ['en']), ('download_url', ''),
+                          ('latest_branch_name', 'main'), ('html_zip', '')]:
+        if name not in app.config:
+            app.add_config_value(name, default, 'html')
+    if 'idf_targets' not in app.config:
+        app.add_config_value('idf_targets', None, 'env')
+    app.connect('config-inited', _espp_html, priority=900)
+    return ret
diff --git a/doc/en/_static/espp-logo.png b/doc/en/_static/espp-logo.png
diff --git a/doc/en/_static/espp.css b/doc/en/_static/espp.css
@@ -0,0 +1,15 @@
+/* espp additions on top of pydata-sphinx-theme */
+
+/* Doxygen-generated API blocks: give the signatures room and keep long
+   template names from pushing the page sideways. */
+.sig {
+  overflow-x: auto;
+}
+
+/* Mermaid diagrams are rendered client-side; keep them inside the content
+   column in both themes. */
+.mermaid {
+  display: flex;
+  justify-content: center;
+  overflow-x: auto;
+}
diff --git a/doc/en/_static/favicon.png b/doc/en/_static/favicon.png
diff --git a/doc/en/api_reference.rst b/doc/en/api_reference.rst
@@ -0,0 +1,124 @@
+API Reference
+=============
+
+Every espp component, grouped by capability. Each group's page lists its
+components with a short description; a component's page carries the usage
+notes, the example, and the API generated from its headers.
+
+.. _api-core-rtos:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Core & RTOS
+
+   core/index
+   coredump/index
+   system/index
+   desktop/index
+
+.. _api-storage-configuration:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Storage & Configuration
+
+   storage/index
+
+.. _api-buses-i-o:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Buses & I/O
+
+   buses/index
+   io_expander/index
+
+.. _api-sensors:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Sensors
+
+   adc/index
+   imu/index
+   encoder/index
+   distance_sensors/index
+   presence/index
+   battery/index
+   power/index
+   rtc/index
+   thermistor
+
+.. _api-motor-control:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Motor Control
+
+   motor_control/index
+   bldc/index
+
+.. _api-audio:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Audio
+
+   audio/index
+
+.. _api-displays-leds-haptics:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Displays, LEDs & Haptics
+
+   display/index
+   leds/index
+   led_driver/index
+   haptics/index
+
+.. _api-input-hid:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Input & HID
+
+   input/index
+   hid/index
+
+.. _api-connectivity-protocols:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Connectivity & Protocols
+
+   network/index
+   wifi/index
+   ble/index
+   ftp/index
+   nfc/index
+   ota/index
+   stream_frame/index
+   dispatcher/index
+   telemetry/index
+   wdi/index
+   wireless/index
+   protocols/index
+
+.. _api-math-dsp:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Math & DSP
+
+   math/index
+   filters/index
+
+.. _api-data-serialization:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Data & Serialization
+
+   data/index
+
diff --git a/doc/en/index.rst b/doc/en/index.rst
@@ -5,116 +5,33 @@ This is the documentation for the ESP-IDF C++ library `espp
 <https://github.com/esp-cpp/espp>`_. ESPP provides additional C++ components and
 abstractions for building applications from reusable components.
 
-New here? Start with :doc:`getting_started`. The APIs below are grouped by
-capability; all supported development boards are collected under
-:doc:`dev_boards/index`. Browser tools for interacting with your hardware are
-collected under :doc:`web_apps`.
+New here? Start with :doc:`getting_started`. The :doc:`api_reference` groups
+every component by capability; all supported development boards are collected
+under :doc:`dev_boards/index`. Browser tools for interacting with your hardware
+are collected under :doc:`web_apps`, and :doc:`qemu` shows how to run espp code
+with no hardware at all.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Introduction
+   :hidden:
 
    getting_started
+   api_reference
+   dev_boards/index
    web_apps
    qemu
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Core & RTOS
-
-   core/index
-   coredump/index
-   system/index
-   desktop/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Storage & Configuration
-
-   storage/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Buses & I/O
-
-   buses/index
-   io_expander/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Sensors
-
-   adc/index
-   imu/index
-   encoder/index
-   distance_sensors/index
-   presence/index
-   battery/index
-   power/index
-   rtc/index
-   thermistor
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Motor Control
-
-   motor_control/index
-   bldc/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Audio
-
-   audio/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Displays, LEDs & Haptics
-
-   display/index
-   leds/index
-   led_driver/index
-   haptics/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Input & HID
-
-   input/index
-   hid/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Connectivity & Protocols
-
-   network/index
-   wifi/index
-   ble/index
-   ftp/index
-   nfc/index
-   ota/index
-   stream_frame/index
-   dispatcher/index
-   telemetry/index
-   wdi/index
-   wireless/index
-   protocols/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Math & DSP
-
-   math/index
-   filters/index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Data & Serialization
-
-   data/index
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Dev Boards (BSPs)
-
-   dev_boards/index
+Components by capability
+------------------------
+
+- :ref:`Core & RTOS <api-core-rtos>`
+- :ref:`Storage & Configuration <api-storage-configuration>`
+- :ref:`Buses & I/O <api-buses-i-o>`
+- :ref:`Sensors <api-sensors>`
+- :ref:`Motor Control <api-motor-control>`
+- :ref:`Audio <api-audio>`
+- :ref:`Displays, LEDs & Haptics <api-displays-leds-haptics>`
+- :ref:`Input & HID <api-input-hid>`
+- :ref:`Connectivity & Protocols <api-connectivity-protocols>`
+- :ref:`Math & DSP <api-math-dsp>`
+- :ref:`Data & Serialization <api-data-serialization>`