Documentation Add-ons and Extensions Reference¶
This documentation is created using Sphinx application that renders text source files in reStructuredText (
.rst) format located in docs directory. For some more details on that process, please refer to section Documenting Code.
Besides Sphinx there are several other applications that help to provide nicely formatted and easy to navigate documentation. These applications are listed in section Setup for building documentation locally with the installed version numbers provided in file docs/requirements.txt.
On top of that we have created a couple of custom add-ons and extensions to help integrate documentation with underlining ESP-IDF repository and further improve navigation as well as maintenance of documentation.
The purpose of this section is to provide a quick reference to the add-ons and the extensions.
Documentation Folder Structure¶
- The ESP-IDF repository contains a dedicated documentation folder docs in the root.
docsfolder contains localized documentation in docs/en (English) and docs/zh_CN (simplified Chinese) subfolders.
- Graphics files and fonts common to localized documentation are contained in docs/_static subfolder
- Remaining files in the root of
docsas well as
docs/zh_CNprovide configuration and scripts used to automate documentation processing including the add-ons and extensions.
- Several folders and files are generated dynamically during documentations build and placed primarily in
docs/[lang]/_buildfolders. These folders are temporary and not visible in ESP-IDF repository,
Add-ons and Extensions Reference¶
- This file contains configuration common to each localized documentation (e.g. English, Chinese). The contents of this file is imported to standard Sphinx configuration file
conf.pylocated in respective language folders (e.g.
docs/zh_CN) during build for each language.
- If there are any warnings reported during documentation build, then the build is failed. The warnings should be resolved before merging any documentation updates. This script is doing check for warnings in respective log file to fail the build. See also description of
To reduce potential discrepancies when maintaining concurrent language version, the structure and filenames of language folders
docs/zh_CNfolders should be kept identical. The script
check_lang_folder_sync.shis run on each documentation build to verify if this condition is met.
If a new content is provided in e.g. English, and there is no any translation yet, then the corresponding file in
zh_CNfolder should contain an
.. include::directive pointing to the source file in English. This will automatically include the English version visible to Chinese readers. For example if a file
docs/zh_CN/contribute/documenting-code.rstdoes not have a Chinese translation, then it should contain
.. include:: ../../en/contribute/documenting-code.rstinstead.
- It contains the common code which is included into the language-specific
Makefiles. Note that this file contains couple of customizations comparing to what is provided within standard Sphinx installation, e.g.
gh-linkcheckcommand has been added.
- A Python script that generates API reference files based on Doxygen
xmloutput. The files have an
incextension and are located in
docs/[lang]/_build/incdirectory created dynamically when documentation is build. Please refer to Documenting Code and API Documentation Template, section API Reference for additional details on this process.
- There couple of places in documentation that provide links to download the toolchain. To provide one source of this information and reduce effort 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.
- Another Python script to automatically generate reStructuredText Text
.incsnippets with version-based content for this ESP-IDF version.
- During documentation lifetime some source files are moved between folders or renamed. This Python script is adding a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list
html_redirect_pagesdefined in file docs/conf_common.py.
- This is an implementation of a custom Sphinx Roles to help linking from documentation to specific files and folders in ESP-IDF. For description of implemented roles please see Linking Examples and Linking Language Versions.
- A collection of utility functions useful primarily when building documentation locally (see Setup for building documentation locally) to reduce the time to generate documentation on a second and subsequent builds. The utility functions check what Doxygen
xmlinput files have been changed and copy these files to destination folders, so only the changed files are used during build process.
- There are couple of spurious Sphinx warnings that cannot be resolved without doing update to the Sphinx source code itself. For such specific cases respective warnings are documented in
sphinx-known-warnings.txtfile, that is checked during documentation build, to ignore the spurious warnings.
- This script is traversing the ESP-IDF directory structure looking for error codes and messages in source code header files to generate an
.incfile to include in documentation under Error Codes Reference.
- Options to configure ESP-IDF’s components are contained in
Kconfigfiles located inside directories of individual components, e.g. components/bt/Kconfig. This script is traversing the
componentdirectories to collect configuration options and generate an
.incfile to include in documentation under Configuration Options Reference.