ReadTheDocs builds failing

[raucao]

They started failing regardless of source code almost exactly 1 day ago:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/remotestoragejs/conda/1259/lib/python3.8/site-packages/pkg_resources/__init__.py", line 2208, in _handle_ns
    loader = importer.find_spec(packageName).loader
  File "<frozen importlib._bootstrap_external>", line 1466, in find_spec
  File "<frozen importlib._bootstrap_external>", line 64, in _path_join
  File "<frozen importlib._bootstrap_external>", line 64, in <listcomp>
AttributeError: 'PosixPath' object has no attribute 'rstrip'

@pjbollinger Maybe you have an idea?

[raucao]

... had a quick look at https://github.com/readthedocs/readthedocs-docker-images and it doesn't seem like there are any recent changes to the images.

[pjbollinger]

@raucao Looking at the last successful build logs and the first failed build logs, I'm noticing that Sphinx is being automatically upgraded from 4.3.2 to 4.4.0. This matches with the release history of Sphinx: https://pypi.org/project/Sphinx/#history

As a quick fix, you could pin just Sphinx in doc/requirements.txt like so:

sphinx==4.3.2

I made a PR here: #1263

A longer term fix, we could have two different requirements.txt files. One where you specify the base requirements needed, let's call it requirements-simple.txt. And then requirements.txt would contain a frozen list of all dependencies. Think of it like having dependencies defined in a package.json file vs a package-lock.json file in JS. I've started to use this approach recently for new Python projects because dependency upgrades can be painful as we see here. 😆

and/or

We could figure out why the error is coming up in the first place so the docs can live longer and not be tied down to a specific version. 😅

[pjbollinger]

After more research, I did discover this comment: pypa/setuptools#2548 (comment)

I opened a new PR #1264. If it works, I will close the other one, since this new PR is a more favorable solution. Freezing dependencies wouldn't be a bad thing to do if you didn't want to worry about random builds failing due to updates.

[raucao]

Yeah, I think freezing dependency versions is not a bad idea. We don't usually want to touch the documentation build process outside of planned documentation setup upgrades, and the aren't really any considerable attack vectors I can think of when it comes to security there.