[finger563]

Summary

First stage of the docs rework: the site moves from esp-docs' sphinx_idf_theme to pydata-sphinx-theme (the NumPy / pandas / Jupyter docs theme). esp-docs still runs Doxygen and provides the API directives; only the look and the navigation change.

• No chip selector, no ESP-IDF version list, espp's logo and favicon. Both selectors were the old theme's (fed by Espressif's own version file); the Espressif logo was forced by esp-docs at extension load, so a small config-inited hook behind esp-docs' own replaces it. The logo is the esp-cpp organisation image with its background lifted; a proper SVG can drop in later.
• The layout you get: a top bar with Getting Started, API Reference, Dev Boards, Web Apps and QEMU, the section navigation on the left (collapsible, and a panel of its own that scrolls under the wheel), the page outline and an "Edit on GitHub" button on the right, breadcrumbs, previous / next, light and dark modes following the system with a toggle, search with a keyboard shortcut, GitHub and Discord links.
• Navigation restructured for it. The index had thirteen captioned toctrees, which this theme turns into a navbar that overflows into "More". A new api_reference page holds the capability groups (the captions become sidebar headings), and the index keeps a short top-level toctree plus a list of the groups.
• Version switcher left for stage two: the theme's switcher takes a JSON file we host, which the versioned-publishing workflow (latest plus one entry per release/v* branch) will generate. The option is in conf_common.py, commented, ready for it.
• Build environment: docutils<0.21 pinned in doc/requirements.txt (esp-docs' target-substitution extension imports a module docutils 0.21 removed; the theme would otherwise pull a newer docutils); the old theme's config values that esp-docs' LaTeX and html-zip extensions still read are registered by our setup(). doc/README.md gains the recipe for building locally without Docker.

Nothing about the published layout changes in this PR (still the site root); the workflow is untouched.

Test plan

• Full local build (Doxygen + Sphinx) with the CI requirements; the warnings are the same families as before (Breathe duplicate declarations, a few signatures the C++ parser cannot read), none from the theme
• Rendered in Chrome: index, section pages, a long API page; dark and light modes; the left panel scrolls under the wheel on its own; logo, favicon, GitHub and Discord links, edit button, search
• CI docs workflow builds and publishes it

🤖 Generated with Claude Code

https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

🟢 Approval recommended

No active review issues remain for the documentation theme and navigation changes.

No open issues 🎉

What changed in this PR

This PR starts the documentation redesign by replacing the ESP-IDF theme with pydata-sphinx-theme, while retaining esp-docs for Doxygen and API integration. Publishing remains unchanged.

Changes:

• Configure espp branding, navigation, sidebars, and light/dark theme support.
• Move capability groups into a dedicated API Reference page and simplify top-level navigation.
• Add theme dependencies, compatibility configuration, and native build instructions.

File	Description
doc/​requirements.txt	Add the new theme and pin docutils for esp-docs compatibility.
doc/​README.md	Document local builds without Docker.
doc/​en/​index.rst	Simplify navigation and link to API capability groups.
doc/​en/​api_reference.rst	Collect component groups into a dedicated API landing page.
doc/​en/​_static/​espp.css	Add horizontal overflow handling for signatures and diagrams.
doc/​conf_common.py	Configure the theme, branding, navigation, and esp-docs compatibility hooks.

_{Review effort: Balanced}