Skip to content
Fork of the Read The Docs Sphinx theme, used for ESP-IDF documentation
CSS HTML JavaScript Python
Branch: master
Clone or download
This branch is 9 commits ahead, 7 commits behind readthedocs:master.

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


ESP-IDF Sphinx Theme

This is a fork of sphinx-rtd-theme by Read The Docs. This fork is used by the ESP-IDF Programming Guide. Espressif forked this theme when we moved ESP-IDF Programming Guide away from Read The Docs' hosted service and needed some functionality that neither RTD nor the theme provide out of the box.

Notes for ESP-IDF Theme

Development Builds

This theme must be imported as a Python package not using Sphinx's html_theme_path option, as it relies on some code in To debug the theme in development, develop doesn't seem to work out of the box (can probably be made to work easily, please update this file if you know the steps). The following hacky approach definitely works:

  • Run python3 build in this directory.
  • In top of IDF docs, add a temporary sys.path.append('/path/to/here/build/lib').
  • Run IDF docs build, it will import the just-built theme from this directory as a package.
  • (When changing theme, re-run build).


  • New JavaScript file idf_embeds.js is compiled into theme.js, sets up version footer.
  • Templates for layout & versions.html have been modified.

To Use In a Sphinx Project

Set the following additional config variables in the Sphinx project:

  • idf_target - slug of the IDF target (ie esp32, esp32s2). Optional, but either both this option and idf_targets must be set or neither must be set.
  • idf_targets - Python list with short names of all supported IDF targets (ie ["esp32", "esp32s2"]).
  • languages - Python list with short names of all supported languages (ie ["en", "zh_CN"]). Must be set to at least one language element (the current project's language)
  • project_slug - short name of the project as a URL slug (ie esp-idf)
  • versions_url - URL to download the versions.js file from
  • project_homepage - URL of the project's main page (GitHub, etc)

Versions file

The file found at the versions_url location should be a JavaScript file describing all current versions. It should take this form:

        "DEFAULTS": { "has_targets": false },
        "VERSIONS": [
            { "name": "latest", "has_targets": true },
            { "name": "v4.0" },
            { "name": "v3.3.1" },
            { "name": "v3.3", "old": true  },
            { "name": "v3.2.3" },
            { "name": "v3.2.2", "old": true },
            { "name": "v3.1.6" },
            { "name": "v3.1.5", "old": true },
            { "name": "v3.0.9", "old": true },
            { "name": "v4.0-rc", "pre_release": true },
            { "name": "v4.0-beta2", "pre_release": true },
            { "name": "release-v4.1", "pre_release": true },
            { "name": "release-v4.0", "pre_release": true },
            { "name": "release-v3.3", "pre_release": true },
            { "name": "release-v3.2", "pre_release": true },
            { "name": "release-v3.1", "pre_release": true },


This file is JavaScript so it can be easily included in a script tag, but in the future it may be parsed elsewhere. Therefore is should contain a single assignment statement which assigns the DOCUMENTATION_VERSIONS variable to a valid JSON object. Including any other JavaScript computation in this file is invalid.


  • VERSIONS key is a list of versions, where each version is a JSON object with at minimum a name key which is the version name "slug", and optionally one or more of the following keys: - has_targets is true if the URLs for these docs have a target element, ie <project>/<language>/<version>/<target>. False if the URL format is <project>/<language>/<version>. A single project can have some versions which include and some which exclude the target URL component, and the theme will try to generate version links that add or drop the <target> element as applicable. - old is true if this version is not current, will be shown in "Old Versions" section under the main versions. - pre_release is true if this version is a prerelease not a stable release, will be shown in "Prereleases" section under the main versions
  • DEFAULTS key contains the default values for any keys which are not supplied in an individual version object. This exists as "sugar" to make the file more readable.

Original RTD Theme README

Pypi Version Build Status License Documentation Status

This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devices. This theme is used primarily on Read the Docs but can work with any Sphinx project. You can find a working demo of the theme in the theme documentation


This theme is distributed on PyPI and can be installed with pip:

$ pip install sphinx-rtd-theme

To use the theme in your Sphinx project, you will need to add the following to your file:

import sphinx_idf_theme

extensions = [

html_theme = "sphinx_idf_theme"

For more information read the full documentation on installing the theme


This theme is highly customizable on both the page level and on a global level. To see all the possible configuration options, read the documentation on configuring the theme.


If you would like to help modify or translate the theme, you'll find more information on contributing in our contributing guide.

You can’t perform that action at this time.