search

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
22 stars 14 forks source link

mysterious sphinx error #1

Closed rytis-paskauskas closed 2 years ago

rytis-paskauskas commented 2 years ago

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.

ESP-Marius commented 2 years ago

Hi, sorry for the late reply.

build_docs.py injects a environment variable called BUILDDIR, which is missing if you call sphinx directly like this. You can try exporting this before running it. It's the link to the build directory for the docs (the build output), so e.g. path-to/esp-idf/path-to/esp-idf/docs/en /path-to/esp-idf/docs/_build/en/esp32 in your case.

Just curious, any reason why you need to invoke it this way instead of letting build-docs handle it?