Adding Extensions

Sometimes your project might need features that the ESP-Docs package does not support yet. In this case, you may add extensions either to ESP-Docs or to your project.

This document describes how to add third-party extensions and self-developed extensions to ESP-Docs or your project.

Where to Add?

An extension can be added either to ESP-Docs or to your project depending on the range of use.

If the extension might be used later in other projects integrating ESP-Docs, then add it to ESP-Docs. Otherwise, add it to your own project.

Third-Party Extensions

Third-party extensions are those extensions contributed by other users, for example extensions in LinuxDoc and sphinx-contrib libraries.

• To add a third-party extension to ESP-Docs, you should:

  1. Add the extension to src/esp_docs/conf_docs.py of ESP-Docs.

     extensions = ['breathe',
                 'sphinx.ext.todo',
                 'sphinx_idf_theme',
                 ]
     

  2. Add the extension and its version to setup.cfg of ESP-Docs.

     install_requires =
             sphinx==4.5.0
             breathe==4.33.1
     

• To add a third-party extension to your project, you should:

  1. Add the extension to docs/conf_common.py of your project, or to the language specific configuration file docs/$lang$/conf.py of your project.

     extensions = ['sphinx_copybutton',
                 'sphinxcontrib.wavedrom',
                 'linuxdoc.rstFlatTable',
                 ]
     

  2. Add the extension and its version to docs/requirements.txt of your project.

     linuxdoc==20210324
     sphinx-design==0.2.0
     

Self-Developed Extensions

Self-developed extensions are those local extensions created by you and not provided as a package.

• To add a self-developed extension to ESP-Docs, you should:

  1. Place the extension in one of the following three folders of ESP-Docs:

     • src/esp_docs/generic_extensions, for extensions that do not rely on any Espressif-docs-specific behavior or configuration.

     • src/esp_docs/esp_extensions, for extensions that rely on any Espressif-docs-specific behavior or configuration.

     • src/esp_docs/idf_extensions, for extensions that rely on ESP-IDF-docs-specific behavior or configuration.

     For more information about self-developed extension types, you may refer to Extensions Developed by Espressif.

  2. Add the extension to src/esp_docs/conf_docs.py of ESP-Docs:

     extensions = ['esp_docs.generic_extensions.html_redirects',
                 'esp_docs.esp_extensions.include_build_file',
                 ]
     

• To add a self-developed extension to your project, you should:

  1. Place the extension in a proper folder of your project.

     For example, in the esp-iot-solution repository, the self-developed extension link-roles.py is placed in the docs folder.

  2. Add the extension to docs/conf_common.py of your project, or to the language specific configuration file docs/$lang$/conf.py of your project.

     extensions = ['link-roles',
                 ]
     

Provide feedback about this document