Building documentation doesn't work in Python 3.12

[ChrisJefferson]

There isn't really anyything to currently be done about this, I'm mainly reporting it so other people will hopefully waste less time than me :)

sphinxcontrib.bibtex (which is used in conjure's docs) doesn't work in Python 3.12. It's a known problem, and doesn't look like it will be fixed any time soon, just lack of time for people working on various libraries.

You get the following error:

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v7.2.6

Extension error:
Could not import extension sphinxcontrib.bibtex (exception: No module named 'pkg_resources')
make: *** [Makefile:51: html] Error 2

[ott2]

It looks like the missing dependency was fixed on 22 April 2024, but the version of pybtex that pip installs is from 2021. I will try working around this by adding setuptools as a dependency explicitly.

[ott2]

Adding setuptools to docs/requirements.txt seems to get past the error. After installing pandoc, running make docs produces most of the documentation for me.