191 lines
13 KiB
ReStructuredText
191 lines
13 KiB
ReStructuredText
Documentation Add-ons and Extensions Reference
|
|
==============================================
|
|
|
|
This documentation is created using `Sphinx <http://www.sphinx-doc.org/>`_ application that renders text source files in `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_ (``.rst``) format located in :idf:`docs` directory. For some more details on that process, please refer to section :doc:`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 :ref:`setup-for-building-documentation` with the installed version numbers provided in file :idf_file:`docs/requirements.txt`.
|
|
|
|
We build ESP-IDF documentation for two languages (English, Simplified Chinese) and for multiple chips. Therefore we don't run ``sphinx`` directly, there is a wrapper Python program ``build_docs.py`` that runs Sphinx.
|
|
|
|
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 :idf:`docs` in the root.
|
|
* The ``docs`` folder contains localized documentation in :idf:`docs/en` (English) and :idf:`docs/zh_CN` (simplified Chinese) subfolders.
|
|
* Graphics files and fonts common to localized documentation are contained in :idf:`docs/_static` subfolder
|
|
* Remaining files in the root of ``docs`` as well as ``docs/en`` and ``docs/zh_CN`` provide configuration and scripts used to automate documentation processing including the add-ons and extensions.
|
|
* Sphinx extensions are provided in two directories, ``extensions`` and ``idf_extensions``
|
|
* A ``_build`` directory is created in the ``docs`` folder by ``build_docs.py``. This directory is not added to the `ESP-IDF`_ repository.
|
|
|
|
|
|
Add-ons and Extensions Reference
|
|
--------------------------------
|
|
|
|
Config Files
|
|
^^^^^^^^^^^^
|
|
|
|
:idf_file:`docs/conf_common.py`
|
|
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.py`` located in respective language folders (e.g. ``docs/en``, ``docs/zh_CN``) during build for each language.
|
|
|
|
:idf_file:`docs/sphinx-known-warnings.txt`
|
|
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.txt`` file, that is checked during documentation build, to ignore the spurious warnings.
|
|
|
|
|
|
Scripts
|
|
^^^^^^^
|
|
|
|
:idf_file:`docs/build_docs.py`
|
|
|
|
Top-level executable program which runs a Sphinx build for one or more language/target combinations. Run ``build_docs.py --help`` for full command line options.
|
|
|
|
When ``build_docs.py`` runs Sphinx it sets the ``idf_target`` configuration variable, sets a Sphinx tag with the same name as the configuration variable, and uses some environment variables to communicate paths to :ref:`IDF-Specific Extensions`.
|
|
|
|
:idf_file:`docs/check_lang_folder_sync.sh`
|
|
To reduce potential discrepancies when maintaining concurrent language version, the structure and filenames of language folders ``docs/en`` and ``docs/zh_CN`` folders should be kept identical. The script ``check_lang_folder_sync.sh`` is run on each documentation build to verify if this condition is met.
|
|
|
|
.. note::
|
|
|
|
If a new content is provided in e.g. English, and there is no any translation yet, then the corresponding file in ``zh_CN`` folder 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.rst`` does not have a Chinese translation, then it should contain ``.. include:: ../../en/contribute/documenting-code.rst`` instead.
|
|
|
|
Non-Docs Scripts
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
These scripts are used to build docs but also used for other purposes:
|
|
|
|
:idf_file:`tools/gen_esp_err_to_name.py`
|
|
This script is traversing the `ESP-IDF`_ directory structure looking for error codes and messages in source code header files to generate an ``.inc`` file to include in documentation under :doc:`../api-reference/error-codes`.
|
|
|
|
:idf_file:`tools/kconfig_new/confgen.py`
|
|
Options to configure ESP-IDF's :idf:`components` are contained in ``Kconfig`` files located inside directories of individual components, e.g. :idf_file:`components/bt/Kconfig`. This script is traversing the ``component`` directories to collect configuration options and generate an ``.inc`` file to include in documentation under :ref:`configuration-options-reference`.
|
|
|
|
Generic Extensions
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
These are Sphinx extensions developed for IDF that don't rely on any IDF-docs-specific behaviour or configuration:
|
|
|
|
:idf_file:`docs/extensions/toctree_filter.py`
|
|
Sphinx extensions overrides the ``:toctree:`` directive to allow filtering entries based on whether a tag is set, as ``:tagname: toctree_entry``. See the Python file for a more complete description.
|
|
|
|
:idf_file:`docs/extensions/list_filter.py`
|
|
Sphinx extensions that 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.
|
|
|
|
:idf_file:`docs/extensions/html_redirects.py`
|
|
During documentation lifetime some source files are moved between folders or renamed. This Sphinx extension adds 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_pages``. ``conf_common.py`` builds this list from :idf_file:`docs/page_redirects.txt`
|
|
|
|
|
|
Third Party Extensions
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
- ``sphinxcontrib`` extensions for blockdiag, seqdiag, actdiag, nwdiag, rackdiag & packetdiag diagrams.
|
|
- `Sphinx selective exclude`_ ``eager_only`` extension
|
|
|
|
.. _idf-specific extensions:
|
|
|
|
IDF-Specific Extensions
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Build System Integration
|
|
########################
|
|
|
|
:idf:`docs/idf_extensions/build_system/`
|
|
|
|
Python package implementing a Sphinx extension to pull IDF build system information into the docs build
|
|
|
|
* Creates a dummy CMake IDF project and runs CMake to generate metadata
|
|
* Registers some new configuration variables and emits a new Sphinx event, both 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``, default will be like ``_build/<lang>/<target>``
|
|
* ``idf_target`` - The IDF_TARGET value. Expected that ``build_docs.py`` set this on the Sphinx command line
|
|
|
|
New Event
|
|
@@@@@@@@@
|
|
|
|
``idf-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.
|
|
|
|
Other Extensions
|
|
################
|
|
|
|
:idf_file:`docs/idf_extensions/include_build_file.py`
|
|
The ``include-build-file`` directive is like the built-in ``include-file`` directive, but file path is evaluated relative to ``build_dir``.
|
|
|
|
:idf_file:`docs/idf_extensions/kconfig_reference.py`
|
|
Subscribes to ``idf-info`` event and uses confgen to generate ``kconfig.inc`` from the components included in the default project build. This file is then included into :doc:`/api-reference/kconfig`.
|
|
|
|
:idf_file:`docs/idf_extensions/link_roles.py`
|
|
This is an implementation of a custom `Sphinx Roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ to help linking from documentation to specific files and folders in `ESP-IDF`_. For description of implemented roles please see :ref:`link-custom-roles` and :ref:`link-language-versions`.
|
|
|
|
:idf_file:`docs/idf_extensions/esp_err_definitions.py`
|
|
Small wrapper extension that calls ``gen_esp_err_to_name.py`` and updates the included .rst file if it has changed.
|
|
|
|
:idf_file:`docs/idf_extensions/gen_toolchain_links.py`
|
|
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 :idf_file:`tools/toolchain_versions.mk`.
|
|
|
|
:idf_file:`docs/idf_extensions/gen_version_specific_includes.py`
|
|
Another extension to automatically generate reStructuredText Text ``.inc`` snippets with version-based content for this ESP-IDF version.
|
|
|
|
:idf_file:`docs/idf_extensions/util.py`
|
|
A collection of utility functions useful primarily when building documentation locally (see :ref:`setup-for-building-documentation`) to reduce the time to generate documentation on a second and subsequent builds.
|
|
|
|
:idf_file:`docs/idf_extensions/format_idf_target.py`
|
|
An extension for replacing generic target related names with the idf_target passed to the Sphinx command line.
|
|
This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
|
|
|
|
Also supports markup for defining local (single .rst-file) substitions with the following syntax: {\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"}
|
|
|
|
This will define a replacement of the tag {\IDF_TARGET_TX_PIN} in the current rst-file.
|
|
|
|
The extension also overrides the default ``.. include::`` directive in order to format any included content using the same rules.
|
|
|
|
These replacements cannot be used inside markup that rely on alignment of characters, e.g. tables.
|
|
|
|
:idf_file:`docs/idf_extensions/latex_builder.py`
|
|
An extension for adding ESP-IDF specific functionality to the latex builder. Overrides the default Sphinx latex builder.
|
|
|
|
Creates and adds the espidf.sty latex package to the output directory, which contains some macros for run-time variables such as IDF-Target.
|
|
|
|
:idf_file:`docs/idf_extensions/gen_defines.py`
|
|
Sphinx extension to integrate defines from IDF into the Sphinx build, runs after the IDF dummy project has been built.
|
|
|
|
Parses defines and adds them as sphinx tags.
|
|
|
|
Emits the new 'idf-defines-generated' event which has a dictionary of raw text define values that other extensions can use to generate relevant data.
|
|
|
|
:idf_file:`docs/idf_extensions/exclude_docs.py`
|
|
Sphinx extension that updates the excluded documents according to the conditional_include_dict {tag:documents}. If the tag is set, then the list of documents will be included.
|
|
|
|
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.
|
|
|
|
Subscribes to ``idf-defines-generated`` as it relies on the sphinx tags to determine which documents to exclude
|
|
|
|
:idf_file:`docs/idf_extensions/run_doxygen.py`
|
|
Subscribes to ``idf-defines-generated`` event and runs Doxygen (:idf_file:`docs/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.
|
|
|
|
Please refer to :doc:`documenting-code` and :doc:`../api-reference/template`, section **API Reference** for additional details on this process.
|
|
|
|
Related Documents
|
|
-----------------
|
|
|
|
* :doc:`documenting-code`
|
|
|
|
|
|
.. _ESP-IDF: https://github.com/espressif/esp-idf/
|
|
.. _Sphinx selective exclude: https://github.com/pfalcon/sphinx_selective_exclude
|