Remove docutils pin from tox configuration

[sajith]

In tox.ini, [testenv:docs] has pinned docutils 0.12 because of this old, no longer relevant bug:

​https://sourceforge.net/p/docutils/bugs/301/

[exarkun]

Is there a benefit to upgrading docutils?

If so, let's pin a new version instead of picking up a new unpinned dependency that can break our stuff.

[sajith]

If I understand correctly, docutils is a dependency of Sphinx, and the bug that made the pin necessary has been fixed in Sphinx. There should be no docutils dependency in [testenv:docs].

I don't know why the ​related PR is failing in CI. Removing docutils worked for me in local testing, on both macOS and Debian.

[exarkun]

There should be no docutils dependency in [testenv:docs].

Why is this the case - if the pinned dependency there makes it work?

[sajith]

Originally the pin was at docutils==0.12 (2014 July vintage), because of a specific bug about the handling SVG files. Sphinx fixed that bug in 2016 December, and docutils is a dependency only via Sphinx, so the comment about having to pin docutils because of that bug is no longer valid.

I don't think it was the pinned dependency that made tox -e docs work. My guess is that CI failure was something transient, because it went away when I re-ran the job. This was the error:

#!/bin/bash -eo pipefail
/tmp/venv/bin/tox -e docs

docs create: /root/project/.tox/docs
docs installdeps: sphinx, recommonmark, sphinx_rtd_theme
docs installed: alabaster==0.7.12,Babel==2.9.0,certifi==2020.12.5,chardet==4.0.0,commonmark==0.9.1,docutils==0.17,idna==2.10,imagesize==1.2.0,Jinja2==2.11.3,MarkupSafe==1.1.1,packaging==20.9,Pygments==2.8.1,pyparsing==2.4.7,pytz==2021.1,recommonmark==0.7.1,requests==2.25.1,snowballstemmer==2.1.0,Sphinx==3.5.3,sphinx-rtd-theme==0.5.1,sphinxcontrib-applehelp==1.0.2,sphinxcontrib-devhelp==1.0.2,sphinxcontrib-htmlhelp==1.0.3,sphinxcontrib-jsmath==1.0.1,sphinxcontrib-qthelp==1.0.3,sphinxcontrib-serializinghtml==1.1.4,urllib3==1.26.4
docs run-test-pre: PYTHONHASHSEED='1530122825'
docs run-test: commands[0] | sphinx-build -b html -d /root/project/docs/_build/doctrees /root/project/docs /root/project/docs/_build/html
Running Sphinx v3.5.3

Encoding error:
'ascii' codec can't decode byte 0xc2 in position 69: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-yf65zi0c.log, if you want to report the issue to the developers.
ERROR: InvocationError for command /root/project/.tox/docs/bin/sphinx-build -b html -d /root/project/docs/_build/doctrees docs /root/project/docs/_build/html (exited with code 2)
___________________________________ summary ____________________________________
ERROR:   docs: commands failed

Exited with code exit status 1

It does not fail for me locally, and I could not reproduce it on CI for a third or fourth time either. I tried it with two recent versions of docutils (0.16 released on 2020-01-12, 0.17 released on 2021-04-03), both locally and on CI.

[meejah]

If we're pinning anything here, it seems we should pin Sphinx (our direct dependency) right?

[exarkun]

If we're pinning anything here, it seems we should pin Sphinx (our direct dependency) right?

I'm not sure. Sphinx probably doesn't pin its direct dependencies, right? The convention seems to be "declare your dependencies unversioned, or maybe with an extremely liberal and untested version constraint". I wouldn't expect pinning Sphinx to protect against, eg, docutils regressions in a new docutils release. I would only expect it to protect against Sphinx regressions in a new Sphinx release.

The logical conclusion here is that we should pin *everything* - direct and indirect dependencies - not just random dependencies like we do now, nor only direct dependencies. This would protect us against regressions in new releases of everything (at least all Python libraries). It has costs too, obviously. I'm probably willing to put effort into exploring this direction.

[sajith]

Sphinx asks for docutils >= 12 in setup.py. Sphinx also has various versions of docutils in their tox.ini so you can in theory run py36-du14, py36-du15, and so on, but CI seems to test against whatever version of that gets installed from PyPI. That is probably less than ideal.

Would ​pip-tools be useful? Or are there better things?

[meejah]

Replying to exarkun:

If we're pinning anything here, it seems we should pin Sphinx (our direct dependency) right?

I'm not sure. Sphinx probably doesn't pin its direct dependencies, right? The convention seems to be "declare your dependencies unversioned, or maybe with an extremely liberal and untested version constraint".

The best-practices I've seen documented are that libraries should declare minimum dependencies and "programs" (that is, like tahoe or sphinx) should pin exact dependencies. Bonus points for using hashes too.

Since we're using Sphinx as "just a tool", we should pin a Sphinx version that we know and love. I don't know if Sphinx pins its own dependencies (but if it followed best-practices, it should).