Pinning of sphinx version not working

[duetosymmetry]

Details

• Read the Docs project URL: https://readthedocs.org/projects/qnm/
• Build URL (if applicable): https://readthedocs.org/projects/qnm/builds/8647909/
• Read the Docs username (if applicable): duetosymmetry

Expected Result

Attempted to pin version of sphinx to >=1.8.4 in docs/requirements.txt. This is higher than the version of sphinx that is used by default (1.7.9).

Actual Result

pip did indeed install sphinx==1.8.4, but sitewide default version sphinx==1.7.9 was used for sphinx-build.

I don't understand the discrepancy. I tried to get the desired version of sphinx via docs/requirements.txt, and various settings in .readthedocs.yml. If there is something I did not configure correctly, can you please point me in the right direction? Or, if this requires enabling USE_SPHINX_LATEST, can you please enable it for my project?

[humitos]

Hi! Checking the output of your builds, I don't see that sphinx==1.8.4 is being installed.

It seems that your project is pointing to the requirements.txt file from the root of your project and not the one under docs/ directory.

Pointing to the right reqs file will solve your issue.

[duetosymmetry]

Thanks for taking a look @humitos . It is in fact pointing to both, using .readthedocs.yml, like so: https://github.com/duetosymmetry/qnm/blob/master/.readthedocs.yml
You can see pip was called with both requirements files in the build log.

[ericholscher]

Guessing if you switch the order, so you install the docs requirements last, it should work.

[stsewd]

The current order should work, I guess something in how we call the sphinx command.

[stsewd]

Found the problem, when system_packages is active https://github.com/duetosymmetry/qnm/blob/4c6c19a84fc91ef24871d034d7ea04a8aea8dca7/.readthedocs.yml#L12

It would take precedence over the other sphinx version, not sure why. I don't think that's the way it should work.

[duetosymmetry]

Thanks for tracking down the issue, @stsewd! I didn't want the build process to waste time installing numpy/scipy/etc. Do you recommend that I remove system_packages, or wait for a fix to the rtd build code?

[stsewd]

If you really need to use that sphinx version, probably you can just remove system_packages. The only downside is that maybe your build could time out because you are installing those libraries, but not sure, you can give it a try.

I'm still tracking how to fix this.

[stsewd]

Hmm, looks like a bug from the sphinx release, virtualenv or pip :/, I tried installing sphinx==1.8.4 inside the docker container, but I was still getting 1.7, then I tried installing sphinx==1.8.3 and it was successful installed and updated, updating from 1.8.3 to 1.8.4 worked too.

I'm investigating more, but doesn't look like a rtd bug

[duetosymmetry]

Thanks for investigating. I turned off system_packages for now and got everything to build as expected. I also had to pin the version of recommonmark (maybe it should be mentioned in the rtd docs alongside the recommendation of pinning the version of sphinx — if the goal is reproducibility, then one should pin the versions of all dependencies used to build the docs)

[stsewd]

Ok, it's a problem with sphinx==1.8.4 only, I don't know why this is happening, but pinning to sphinx==1.8.3 works as expected. Updating from 1.7 to 1.8.4 doesn't work but updating from 1.7 to 1.8.3 does. Closing this issue as isn't a rtd problem.

[humitos]

The only downside is that maybe your build could time out because you are installing those libraries, but not sure, you can give it a try.

I don't think so. The libraries that we install at system level are now compiled by default and do not take too much time to get installed. In fact, I think we should deprecate the system_package option and remove those libs from the Docker image: readthedocs/readthedocs-docker-images#90