Extension error when building sphinx documentation

Development
1

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.

Running Sphinx v8.2.3
loading translations [en]... done

Extension error!

I get the following traceback:

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.

2

when you installed octoprint did you include the docs tag?

source /path/to/venv/Scripts/activate
python -m pip install -e '.[develop,plugins,docs]'
3

Thanks for the reply!

I did run those commands. I just re-ran the pip install to make sure I didn't mess something up. Same result again!

I'm running it on an Ubuntu VM vs. bare metal, but I assume that shouldn't make a difference.

4

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.

5

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.

6

@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.

7

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?