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.
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.
Link Roles ïThis is an implementation of a custom Sphinx Roles to help to link from documentation to specific files and folders in project repositories.
See Links to files on GitHub 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.
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.
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.
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.
There are a couple of places in documentation that provide links to download the toolchain. To provide one source of this information and reduce efforts to manually update several files, this script generates toolchain download links and toolchain unpacking code snippets based on information found in tools/toolchain_versions.mk. These links can be found in List of IDF Tools.
This extension automatically generates reStructuredText .inc snippets with version-based content for this ESP-IDF version, such as git-clone-bash.inc.
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.
HTML/CSS theme for Sphinx based on ReadtheDocsâs Sphinx theme. For more information see the Sphinx-IDF-theme repository.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4