What Is ESP-Docs?

ESP-Docs is a documentation-building system developed by Espressif based on Sphinx and Read the Docs. It expands Sphinx functionality and extensions with the features needed for Espressif’s documentation and bundles this into a single package. It takes text source files written in reStructuredText and builds them into target formats, including HTML and PDF.

ESP-Docs is an open-source and common project. You are always welcome to contribute any functionality! See Contributing Guide for more information.

ESP-Docs is available as a Python package.

Features

ESP-Docs has the following features:

  • Generating documentation for multiple targets from the same source files

  • Generating API documentation automatically for multiple targets from header files

  • Page redirection

  • Linking to a specific file and folder in the project

  • All features already provided by Sphinx, such as:

    • Source text format: reStructuredText

    • Multiple languages: English, Chinese, etc.

    • Output format: HTML, PDF, etc.

    • Extensive cross-references

    • Extensions

Third-Party Extensions

Besides Sphinx, several other third-party applications (extensions) help to provide nicely formatted and easy-to-navigate documentation. These applications are listed together with the installed version numbers as the dependent packages to ESP-Docs in setup.cfg .

  • docutils: open-source text processing system for processing plaintext in reStructuredText into HTML, LaTeX, etc.

  • cairosvg: SVG converter based on Cairo 2D graphics library to export SVG files to PDF, EPS, PS, and PNG files.

  • sphinx: documentation generator, which is the foundation for ESP-Docs.

  • breathe: bridge between the Sphinx and Doxygen documentation systems, making it possible to include Doxygen information in a set of documentation generated by Sphinx.

  • sphinx-copybutton: Sphinx extension to add a “copy” button to code blocks.

  • sphinx-notfound-page: Sphinx extension to create custom 404 pages.

  • sphinxcontrib-blockdiag: Sphinx extension to generate block diagrams from plaintext.

  • sphinxcontrib-seqdiag: Sphinx extension to generate sequence diagrams from plaintext.

  • sphinxcontrib-actdiag: Sphinx extension to generate activity diagrams from plaintext.

  • sphinxcontrib-nwdiag: Sphinx extension to generate network-related diagrams from plaintext.

  • sphinxcontrib-wavedrom: Sphinx extension to generate wavedrom diagrams from plaintext.

  • sphinxcontrib-svg2pdfconverter: sphinx extension to convert SVG images to PDF in case the builder does not support SVG images natively.

  • nwdiag: network diagram generator.

  • recommonmark: a flavor of Markdown. With this package, Sphinx can build documents written in Markdown to target formats.

  • sphinx_selective_exclude: Sphinx extension to make the “only::” directive provided by Sphinx work in an expected and intuitive manner.

Extensions Developed by Espressif

Espressif has created a couple of custom add-ons and extensions to help integrate documentation with underlying Espressif repositories and further improve navigation as well as maintenance of documentation.

The section provides a quick reference to these add-ons and extensions.

Generic Extensions

These Sphinx extensions are developed for Espressif but do not rely on any Espressif-docs-specific behavior or configuration.

Toctree Filter

This Sphinx extension overrides the :toctree: directive to allow filtering entries based on whether a tag is set (similar to how .. only:: does for paragraphs), as :tagname: toctree_entry. See the Python file for a more complete description.

See Target-Specific Document for an example.

List Filter

This Sphinx extension provides a .. list:: directive that allows filtering of entries in lists based on whether a tag is set, as :tagname: - list content. See the Python file for a more complete description.

See Target-Specific Bullet Point for an example.

HTML redirect

During the documentation lifetime, some source files are moved between folders or renamed. This Sphinx extension adds a mechanism to redirect documentation pages that have changed URLs by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list html_redirect_pages. conf_common.py builds this list from docs/page_redirects.txt.

See Redirecting Documents for how to redirect documents.

Add warnings

In some cases, it might be useful to be able to add warnings to a list of documents. This is the case in ESP-IDF when we introduce a new target, which we build docs for, but not all docs are yet updated with useful information. This extension can then be used to give warnings to readers of documents that are not yet updated.

Configuration values:

  • add_warnings_content: content of the warning which will be added to the top of the documents.

  • add_warnings_pages: list of the documents which the warning will be added to.

See conf_commom.py and docs_not_updated of ESP-IDF Programming Guide for an example.

Espressif-Specific Extensions

Run Doxygen

Subscribes to defines-generated event and runs Doxygen (docs/doxygen/Doxyfile) to generate XML files describing key headers, and then runs Breathe to convert these to .inc files which can be included directly into API reference pages.

Pushes a number of target-specific custom environment variables into Doxygen, including all macros defined in the project’s default sdkconfig.h file and all macros defined in all soc component xxx_caps.h headers. This means that public API headers can depend on target-specific configuration options or soc capabilities headers options as #ifdef & #if preprocessor selections in the header.

This means we can generate different Doxygen files, depending on the target we are building docs for.

For headers with unique names the path to the generated .inc will be the header name itself, e.g.: inc/my_header.inc, while for headers with non-unique names the whole header path will be used, e.g.: inc/component/folder/my_header.inc.

See Formatting and Generating API Descriptions for how to generate API description from header files and include it in your documentation.

Exclude Docs

The Sphinx extension updates the excluded documents according to the conditional_include_dict {tag:documents}. If the tag is set, the list of documents will be included.

It is also responsible for excluding documents when building with the config value docs_to_build set. In these cases, all documents not listed in docs_to_build will be excluded.

It subscribes to defines-generated as it relies on the Sphinx tags to determine which documents to exclude.

See Target-Specific Document for an example.

Format ESP Target

This is an extension for replacing generic target-related names with the idf_target passed to the Sphinx command line. It supports markup for defining local (single .rst file) substitutions and it also overrides the default .. include:: directive in order to format any included content using the same rules.

See Target-Specific Inline Text for an example.

Latex Builder

This extension adds ESP-Docs-specific functionality to the LaTeX builder. It overrides the default Sphinx LaTeX builder.

It creates and adds the espidf.sty LaTeX package to the output directory, which contains some macros for run-time variables such as IDF-Target.

Include Build File

The include-build-file directive is like the built-in include-file directive, but the file path is evaluated relative to build_dir.

IDF-Specific Extensions

Build System Integration

This is a Python package implementing a Sphinx extension to pull IDF build system information into the documentation build process:

  • Creates a dummy CMake IDF project and runs CMake to generate metadata.

  • Registers some new configuration variables and emits a new Sphinx event, both of which are for use by other extensions.

Configuration Variables

  • docs_root - The absolute path of the $IDF_PATH/docs directory.

  • idf_path - The value of IDF_PATH variable, or the absolute path of IDF_PATH if environment unset.

  • build_dir - The build directory passed in by build_docs.py, and the default will be like _build/<lang>/<target>.

  • idf_target - The IDF_TARGET value. It is expected that build_docs.py set this on the Sphinx command line.

New Event

project-build-info event is emitted early in the build, after the dummy project CMake run is complete.

Arguments are (app, project_description), where project_description is a dict containing the values parsed from project_description.json in the CMake build directory.

Other IDF-specific extensions subscribe to this event and use it to set up some docs parameters based on build system info.

KConfig Reference

This extension subscribes to project-build-info event and uses confgen to generate kconfig.inc from the components included in the default project build. This file is then included into /api-reference/kconfig.

See Link to Kconfig Reference for an example.

Error to Name

Small wrapper extension that calls gen_esp_err_to_name.py and updates the included .rst file if it has changed.

Generate Version-Specific Includes

This extension automatically generates reStructuredText .inc snippets with version-based content for this ESP-IDF version, such as git-clone-bash.inc.

Generate Defines

This extension integrates defines from IDF into the Sphinx build and runs after the IDF dummy project has been built.

It parses defines and adds them as Sphinx tags.

It emits the new defines-generated event which has a dictionary of raw text define values that other extensions can use to generate relevant data.

Sphinx-IDF-Theme

HTML/CSS theme for Sphinx based on ReadtheDocs’s Sphinx theme. For more information see the Sphinx-IDF-theme repository.

Provide feedback about this document