Readthedocs failing to build: module 'setuptools.build_meta' has no attribute '__legacy__'

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

The horror

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.yml file which specified a separate dependencies.txt file for the docs.
• Adding autodoc_mock_imports = ['hdbscan'] to avoid installation of the dependencies.