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.

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](https://github.com/tahoe-lafs/tahoe-lafs/pull/1031) is failing in CI. Removing docutils worked for me in local testing, on both macOS and Debian.

exarkun commented

2021-04-05 12:07:36 +00:00

Author

Owner

There should be no docutils dependency in testenv:docs.

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

> There should be no docutils dependency in testenv:docs. Why is this the case - if the pinned dependency there makes it work?

sajith commented

2021-04-05 22:17:11 +00:00

Author

Owner

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:

/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.

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 commented

2021-04-10 23:32:44 +00:00

Author

Owner

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

exarkun commented

2021-04-10 23:49:09 +00:00

Author

Owner

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.

> 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 commented

2021-04-13 02:18:38 +00:00

Author

Owner

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?

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](https://pypi.org/project/pip-tools/) be useful? Or are there better things?

meejah commented

2021-04-20 22:27:52 +00:00

Author

Owner

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).

Replying to [exarkun](/tahoe-lafs/trac-2024-07-25/issues/3665#issuecomment-147434): > > 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).