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.

[ott2]

The version of pybtex at pypi is still the 2021 one, whereas the version at bitbucket is more recent. Would it be worth adding setuptools to the requirements? This should be benign even if pybtex at pypi is later updated.