I am setting up a development environment. I am able to run octoprint serve, but cannot build any documentation. When running sphinx-build -M html . _build, I immediately run into an Extension error.
Versions
========
* Platform: linux; (Linux-6.8.0-62-generic-x86_64-with-glibc2.39)
* Python version: 3.12.3 (CPython)
* Sphinx version: 8.2.3
* Docutils version: 0.21.2
* Jinja2 version: 3.1.6
* Pygments version: 2.19.1
Last Messages
=============
None.
Loaded Extensions
=================
None.
Traceback
=========
File "/home/will/Desktop/repos/OctoPrint/venv/lib/python3.12/site-packages/sphinx/registry.py", line 544, in load_extension
raise ExtensionError(
sphinx.errors.ExtensionError: Could not import extension onlineinclude (exception: cannot import name 'parselinenos' from 'sphinx.directives.code' (/home/will/Desktop/repos/OctoPrint/venv/lib/python3.12/site-packages/sphinx/directives/code.py))
I'm not sure how to solve this problem; I tried searching for how to install onlineinclude and parselineos, but it seems like those aren't installable packages. I tried commenting out that line in docs/conf.py, which still raised errors after only a few HTML pages of documentation had been built. Considering this is a current version of the repo, I'm not sure if there is a compatibility mismatch or errors on my part.
The last thing I see related to parselinenos in sphinx is with version 1.5 of that module, which is very old. Not sure how much time I'd invest in this because I think @foosel is switching to mkdocs in the near future.
As mentioned in the last OoA I'm staying with sphinx after all (less problems to switch to markdown), but on the maintenance branch the docs have gotten a lot of work to be compatible with current sphinx versions again, support markdown and have a new look too: OctoPrint maintenance documentation.
For the master branch you should manually install sphinx 4.5 - see also the build matrix here.
@foosel I'm a little confused; I set up a new venv to use sphinx 4.5 and still wasn't able to build the documentation from the master branch.
(venv-docs) will@mint22-xfce-dev:~/Desktop/repos/OctoPrint/docs$ sphinx-build -b html . _build
Running Sphinx v4.5.0
Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
I similarly was not able to build the docs on the maintenance branch. I'm still having the same issue when I try to build the docs on the original venv that has all of the requirements.txt packages installed.
Update: I was able to build documentation on the maintenance branch. However, I was stopped two times to manually install sphinx-immaterial and myst_parser. Should those go in requirements.txt?