As we all know, it’s critical that your code’s github README.md
However, to my horror, I noticed one of my many nice green badges signalling my professionalism had turned an alarming shade of red. What were potential users to think, seeing that the docs for my most recent commit had failed to build on readthedocs
Looking at the build logs, one of my dependencies (in this case hdbscan) was failing with the error message:
AttributeError: module 'setuptools.build_meta' has no attribute '__legacy__'
This issue is apparently caused by certain versions of pip and setuptools in a virtual environment, which appear to be satisfied by the readthedocs build environment: https://github.com/pypa/setuptools/issues/1694
After trying unsuccessfully (with an embarrassingly long series of pushed commits) to fix this through a
readthedocs.yml file, only then did I question why installation of all of the dependencies was required to make the docs. The answer is my use of autodoc (
:automodule:) to make the API documentation from my docstrings. I believe this can also incorporate documentation from external modules, but in this case (and I would guess most cases) this is not necessary. Indeed, sphinx has a parameter you can add to the
conf.py file to pretend the modules are installed when you don’t actually need to install them: https://github.com/sphinx-doc/sphinx/issues/4182.
So, this was caused by:
- Having a ‘requirements.txt’ file being picked up by readthedocs.
- Some of the dependencies causing installation issues within their virtualenv.
- Needing these dependencies to be installed though use of autodoc in places.
I was able to fix it by:
- Adding a
readthedocs.ymlfile which specified a separate
dependencies.txtfile for the docs.
autodoc_mock_imports = ['hdbscan']to avoid installation of the dependencies.