espressif / esp-docs

Python based wrapper for Sphinx, intended to simplify and extend Sphinx's functionality to better suit the documentation needs for Espressif's development frameworks

Espressif Documentation Build System

Esp-docs is a python based wrapper for the documentation building package Sphinx.

It is intended to simplify and extend Sphinx's functionality to better suit what is needed for building documentation for Espressif's development frameworks

Provides:

• Functionality for building documentation for multiple targets (e.g. ESP32 and ESP32-C3) from the same rst source files.
• Sphinx extensions used at Espressif
• Scripts for deploying docs

For a more in-depth guide on how to install, write, and compile documentation please see ESP-Docs User Guide.

esp-docs's Issues

mysterious sphinx error

Guys, never been able to build the docs (but building ESP32 projects with esp-idf goes smoothly, so I guess the installation is OK)
Any help to resolving this issue and pointers towards successfully building the help/manual, will be most appreciated.
Here's the /tmp/sphinx-err-[a-z]*.txt file.

# Sphinx version: 2.3.1
# Python version: 3.9.9 (CPython)
# Docutils version: 0.18.1 release
# Jinja2 version: 3.0.3
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "/home/me/.espressif/python_env/idf5.0_py3.9_env/lib/python3.9/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/me/.espressif/python_env/idf5.0_py3.9_env/lib/python3.9/site-packages/sphinx/application.py", line 257, in __init__
    self.config.setup(self)
  File "/home/me/.espressif/python_env/idf5.0_py3.9_env/lib/python3.9/site-packages/esp_docs/conf_docs.py", line 334, in setup
    app.add_config_value('build_dir', os.environ['BUILDDIR'], 'env')
  File "/usr/lib/python3.9/os.py", line 679, in __getitem__
    raise KeyError(key) from None
KeyError: 'BUILDDIR'

The above is a result of
python -u -m sphinx.cmd.build -j 1 -b html -d /path-to/esp-idf/docs/_build/en/esp32/doctrees -w sphinx-warning-log.txt -t esp32 -D idf_target=esp32 -D docs_to_build= -D config_dir=/path-to/.local/lib/python3.9/site-packages/esp_docs -D doxyfile_dir=/path-to/esp-idf/docs -D project_path=/path-to/esp-idf/path-to/esp-idf/docs/en /path-to/esp-idf/docs/_build/en/esp32/html
which is my translation of build-docs -l en -t esp32, in which I substituted /usr/bin/python with python, the latter being a link to the binaries that the API expects.

The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0

esp-idf is latest version (from today)
esp-docs is latest version (from today)

Directory structure:
esp/esp-idf
esp/esp-docs

Started idf environment using standard export.sh
Environment set up correctly. My project compiles. No issues.

Ran pip install esp-docs after starting esp-idf. Installed no issues.

Ran the following:
cd esp/esp-docs/examples/doxygen
./build_example.sh

Got a lot of errors. I'm guessing that is because the build is run multiple times for different languages and chips.

Ran a shortened version of the command contained in the ./build_example.sh file.

build-docs -l en -t esp32c6 --project-path src/
Which created the following output.

Will use 1 parallel builds and 1 jobs per build
[{'build_dir': '/mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6', 'source_dir': '/mnt/md8/_development/esp/esp-docs/examples/doxygen/en', 'language': 'en', 'target': 'esp32c6', 'sphinx_parallel_jobs': 1, 'builders': ['html'], 'input_docs': [''], 'doxyfile_dir': '.', 'project_path': 'src/'}]
Building in build_dir: /mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6
Running '/home/wilsonj/.espressif/python_env/idf5.3_py3.11_env/bin/python3 -u -m sphinx.cmd.build -j 1 -b html -d /mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6/doctrees -w sphinx-warning-log.txt -t esp32c6 -D idf_target=esp32c6 -D docs_to_build= -D config_dir=/home/wilsonj/.espressif/python_env/idf5.3_py3.11_env/lib/python3.11/site-packages/esp_docs -D doxyfile_dir=/mnt/md8/_development/esp/esp-docs/examples/doxygen -D project_path=/mnt/md8/_development/esp/esp-docs/examples/doxygen/src /mnt/md8/_development/esp/esp-docs/examples/doxygen/en /mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6/html'
en/esp32c6: Running Sphinx v4.5.0
en/esp32c6: Version: v1.4.0-62-gbea28a0074  Release: v1.4.0-62-gbea28a0074
en/esp32c6: fatal: no tag exactly matches 'bea28a0074c5169a5aed3edf4a518f9f4a1e2ef1'
en/esp32c6: Git commit ID:  bea28a0
en/esp32c6: loading translations [en]... done
en/esp32c6: 
en/esp32c6: Sphinx version error:
en/esp32c6: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
/mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6/doxygen-warning-log.txt not generated

en/esp32c6: Build failed due to new/different warnings (/mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6/sphinx-warning-log.txt):

en/esp32c6: 
en/esp32c6: Sphinx version error:
en/esp32c6: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

en/esp32c6: (Check files sphinx-known-warnings.txt and /mnt/md8/_development/esp/esp-docs/examples/doxygen/_build/en/esp32c6/sphinx-warning-log.txt for full details.)
[4]

The following language/target combinations failed to build:
language: en, target: esp32c6, errcode: 4

Without knowing how the program works exactly... I'm guessing that the "fatal: no tag exactly matches" error isn't that important and is related to git.

The actual bug, if I'm correct, is the "The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version".

I did try manually installing version 5, but then the program complained that its requirements were wrong and if I told the program to not check the requirements it also bailed with an error message.

This looks like its a similar bug to googleapis/sphinx-docfx-yaml#344 but I have no idea how to resolve this which is why I'm creating this issue.

Thanks in advance for any help/resolution.

(Edited as the url googleapis/sphinx-docfx-yaml#344 wasn't showing)

Python 3.12 is not supported

The pillow < 10.0.0 requirement from https://github.com/espressif/esp-docs/blob/master/setup.cfg#L24 seems to be incompatible with the recently released Python 3.12. The support and wheels are available from pillow==10.0.0: python-pillow/Pillow#6941 (comment)

This is the log of the failure:

Building wheels for collected packages: netifaces, dbus-python, pygobject, dbus-fast, pillow, pycairo
  Building wheel for netifaces (setup.py): started
  Building wheel for netifaces (setup.py): finished with status 'done'
  Created wheel for netifaces: filename=netifaces-0.11.0-cp312-cp312-linux_x86_64.whl size=35634 sha256=677357025864b370448f0e613a9a79ebd19391421d477786691023bd30f29d7d
  Stored in directory: /tmp/pip-ephem-wheel-cache-pqw4vs_n/wheels/63/fa/57/da80d0ffc8f993315c479b7cd4c8fb1c23910c8baccf6b1b27
  Building wheel for dbus-python (setup.py): started
  Building wheel for dbus-python (setup.py): finished with status 'done'
  Created wheel for dbus-python: filename=dbus_python-1.2.18-cp312-cp312-linux_x86_64.whl size=448808 sha256=78945af561b5cc79437cb70c543018084254d5dae9ca13561d305e3c452443e2
  Stored in directory: /tmp/pip-ephem-wheel-cache-pqw4vs_n/wheels/9d/c8/6a/f51640a0d660f02fe9265d0f736362fbcc170c3313c14be86d
  Building wheel for pygobject (pyproject.toml): started
  Building wheel for pygobject (pyproject.toml): finished with status 'done'
  Created wheel for pygobject: filename=PyGObject-3.46.0-cp312-cp312-linux_x86_64.whl size=843118 sha256=7cfe0a82016094362802b88ce23cbc66eaa4b8eae48f0f71a1735b51cb5331fb
  Stored in directory: /tmp/pip-ephem-wheel-cache-pqw4vs_n/wheels/02/78/ea/58164c9ee67c94c93825a790b81f030ed1ec9dc74e687110cf
  Building wheel for dbus-fast (pyproject.toml): started
  Building wheel for dbus-fast (pyproject.toml): finished with status 'done'
  Created wheel for dbus-fast: filename=dbus_fast-2.11.1-cp312-cp312-manylinux_2_31_x86_64.whl size=5533319 sha256=18e78f204f330d73e4a1d3e37f8cedc90cd78177f16ac6d7db9120228e10e515
  Stored in directory: /tmp/pip-ephem-wheel-cache-pqw4vs_n/wheels/70/52/9a/fdafc304bcaa6b2813faf4d837d55a4384bb2f09f51251355e
  Building wheel for pillow (setup.py): started
  Building wheel for pillow (setup.py): finished with status 'error'
  error: subprocess-exited-with-error
  
  × python setup.py bdist_wheel did not run successfully.
  │ exit code: 1
  ╰─> [191 lines of output]
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build/lib.linux-x86_64-cpython-312
      creating build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/features.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/_version.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/_util.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/_tkinter_finder.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/_deprecate.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/_binary.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/__main__.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/__init__.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/XpmImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/XbmImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/XVThumbImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/WmfImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/WebPImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/WalImageFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/TiffTags.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/TiffImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/TgaImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/TarIO.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/SunImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/SpiderImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/SgiImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/QoiImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PyAccess.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PsdImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PpmImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PngImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PixarImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PdfParser.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PdfImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PcxImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PcfFontFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PcdImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PalmImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PaletteFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/PSDraw.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/MspImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/MpoImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/MpegImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/MicImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/McIdasImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/JpegPresets.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/JpegImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/Jpeg2KImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/IptcImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImtImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageWin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageTransform.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageTk.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageStat.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageShow.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageSequence.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageQt.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImagePath.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImagePalette.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageOps.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageMorph.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageMode.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageMath.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageGrab.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageFont.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageFilter.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageEnhance.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageDraw2.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageDraw.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageColor.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageCms.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImageChops.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/Image.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ImImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/IcoImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/IcnsImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/Hdf5StubImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/GribStubImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/GimpPaletteFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/GimpGradientFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/GifImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/GdImageFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/GbrImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/FtexImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/FpxImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/FontFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/FliImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/FitsStubImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/FitsImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ExifTags.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/EpsImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/DdsImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/DcxImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/CurImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/ContainerIO.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/BufrStubImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/BmpImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/BlpImagePlugin.py -> build/lib.linux-x86_64-cpython-312/PIL
      copying src/PIL/BdfFontFile.py -> build/lib.linux-x86_64-cpython-312/PIL
      running egg_info
      writing src/Pillow.egg-info/PKG-INFO
      writing dependency_links to src/Pillow.egg-info/dependency_links.txt
      writing requirements to src/Pillow.egg-info/requires.txt
      writing top-level names to src/Pillow.egg-info/top_level.txt
      reading manifest file 'src/Pillow.egg-info/SOURCES.txt'
      reading manifest template 'MANIFEST.in'
      warning: no files found matching '*.c'
      warning: no files found matching '*.h'
      warning: no files found matching '*.sh'
      warning: no files found matching '*.txt'
      warning: no previously-included files found matching '.appveyor.yml'
      warning: no previously-included files found matching '.clang-format'
      warning: no previously-included files found matching '.coveragerc'
      warning: no previously-included files found matching '.editorconfig'
      warning: no previously-included files found matching '.readthedocs.yml'
      warning: no previously-included files found matching 'codecov.yml'
      warning: no previously-included files found matching 'renovate.json'
      warning: no previously-included files matching '.git*' found anywhere in distribution
      warning: no previously-included files matching '*.pyc' found anywhere in distribution
      warning: no previously-included files matching '*.so' found anywhere in distribution
      no previously-included directories found matching '.ci'
      adding license file 'LICENSE'
      writing manifest file 'src/Pillow.egg-info/SOURCES.txt'
      running build_ext
      
      
      The headers or library files could not be found for jpeg,
      a required dependency when compiling Pillow from source.
      
      Please see the install instructions at:
         https://pillow.readthedocs.io/en/latest/installation.html
      
      Traceback (most recent call last):
        File "/tmp/pip-install-ru126fzw/pillow_6ef9aa17cdbc4070ac3b36a3d8efb592/setup.py", line 993, in <module>
          setup(
        File "/usr/local/lib/python3.12/site-packages/setuptools/__init__.py", line 103, in setup
          return distutils.core.setup(**attrs)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/core.py", line 185, in setup
          return run_commands(dist)
                 ^^^^^^^^^^^^^^^^^^
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/core.py", line 201, in run_commands
          dist.run_commands()
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/dist.py", line 969, in run_commands
          self.run_command(cmd)
        File "/usr/local/lib/python3.12/site-packages/setuptools/dist.py", line 989, in run_command
          super().run_command(command)
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/dist.py", line 988, in run_command
          cmd_obj.run()
        File "/usr/local/lib/python3.12/site-packages/wheel/bdist_wheel.py", line 364, in run
          self.run_command("build")
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/cmd.py", line 318, in run_command
          self.distribution.run_command(command)
        File "/usr/local/lib/python3.12/site-packages/setuptools/dist.py", line 989, in run_command
          super().run_command(command)
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/dist.py", line 988, in run_command
          cmd_obj.run()
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/command/build.py", line 131, in run
          self.run_command(cmd_name)
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/cmd.py", line 318, in run_command
          self.distribution.run_command(command)
        File "/usr/local/lib/python3.12/site-packages/setuptools/dist.py", line 989, in run_command
          super().run_command(command)
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/dist.py", line 988, in run_command
          cmd_obj.run()
        File "/usr/local/lib/python3.12/site-packages/setuptools/command/build_ext.py", line 88, in run
          _build_ext.run(self)
        File "/usr/local/lib/python3.12/site-packages/setuptools/_distutils/command/build_ext.py", line 345, in run
          self.build_extensions()
        File "/tmp/pip-install-ru126fzw/pillow_6ef9aa17cdbc4070ac3b36a3d8efb592/setup.py", line 809, in build_extensions
          raise RequiredDependencyException(f)
      RequiredDependencyException: jpeg
      
      During handling of the above exception, another exception occurred:
      
      Traceback (most recent call last):
        File "<string>", line 2, in <module>
        File "<pip-setuptools-caller>", line 34, in <module>
        File "/tmp/pip-install-ru126fzw/pillow_6ef9aa17cdbc4070ac3b36a3d8efb592/setup.py", line 1010, in <module>
          raise RequiredDependencyException(msg)
      RequiredDependencyException:
      
      The headers or library files could not be found for jpeg,
      a required dependency when compiling Pillow from source.
      
      Please see the install instructions at:
         https://pillow.readthedocs.io/en/latest/installation.html
      
      
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for pillow

[questions] Multi-target build

Hi team,
i have to say it is really cool tool. Even if there is a bit more work to do it looks much nicer than doxygen generated documentation.

I have the need to build 1 firmware for few hardware revisions, and if its fairly easy to build docs for esp32 chips, i am wondering if there is an option to build for hardware revision instead, since all versions are based on the same chip. Command line only accepts esp32-like targets, also changing targets in versions.js does not help.

Another question is: is there option to block or to change version build on top of non-tag code, when esp-docs is generating links like this

_build/en/v4.0.4-5-g9d4e9af/index.html

I am asking this because i would like for example to add esp-docs to already existing tagged versions. Its not a big deal, because firmware is still in development phase, but would be nice to have.

How to avoid this kind of build error:

en/esp32: If the function has no return type:
en/esp32:   Error in declarator or parameters-and-qualifiers
en/esp32:   Invalid C++ declaration: Expected identifier in nested name, got keyword: const [error at 5]
en/esp32:     const __attribute__ ((section(".rodata_custom_desc"))) custom_app_desc_t custom_app_desc

Last question i have for now is, why esp-docs or sphinx does not accept upper case header files, is it know issue?

Thanks

files displacement

When I run the 'build-docs build' command, multiple "...cannot find the file..." errors occur.
I ran the command from a dos box in the docs subdirectory.
"ModuleNotFoundError: No module named 'conf_common' "
Nothing in the software seems to work.

Missing release tags

Looks like a few recent pypi releases don't have the corresponding tags in the repository. This makes it harder to git checkout the correct version of the repository, matching the version specified in IDF's constraints file.

As an option, we could consider using setuptools_scm, then the git tags can become the single source of truth about the version numbers.