tahoe-lafs/trac-2024-07-25

'tox -e docs' causes exception in docutils #2847

New issue

Closed

opened 2016-12-12 16:15:20 +00:00 by warner · 1 comment

warner commented

2016-12-12 16:15:20 +00:00

Owner

While working on #2835, I noticed that running tox -e docs (to render our docs into HTML, just like Read The Docs does) caused an exception:

writing output... [  1%] INSTALL
writing output... [  3%] OS-X
writing output... [  5%] about

Exception occurred:
  File "/Users/warner/stuff/tahoe/tahoe/.tox/docs/lib/python2.7/site-packages/docutils/writers/_html_base.py", line 671, in depart_document
    assert not self.context, 'len(context) = %s' % len(self.context)
AssertionError: len(context) = 1

It looks like this is a bug (docutils#301) in the latest docutils (0.13.1). It doesn't affect ReadTheDocs because they've pinned older versions of the tools (Docutils-0.12 instead of 0.13.1, Sphinx-1.3.5 instead of 1.5).

The issue appears to involve links to SVG images in our about.rst (although potentially in other docs too). The simplest workaround may simply be to pin docutils to 0.12 in our tox.ini.

While working on #2835, I noticed that running `tox -e docs` (to render our docs into HTML, just like Read The Docs does) caused an exception: ``` writing output... [ 1%] INSTALL writing output... [ 3%] OS-X writing output... [ 5%] about Exception occurred: File "/Users/warner/stuff/tahoe/tahoe/.tox/docs/lib/python2.7/site-packages/docutils/writers/_html_base.py", line 671, in depart_document assert not self.context, 'len(context) = %s' % len(self.context) AssertionError: len(context) = 1 ``` It looks like this is a bug ([docutils#301](https://sourceforge.net/p/docutils/bugs/301/)) in the latest docutils (0.13.1). It doesn't affect ReadTheDocs because they've pinned older versions of the tools (Docutils-0.12 instead of 0.13.1, Sphinx-1.3.5 instead of 1.5). The issue appears to involve links to SVG images in our about.rst (although potentially in other docs too). The simplest workaround may simply be to pin docutils to 0.12 in our tox.ini.

tahoe-lafs added the

labels 2016-12-12 16:15:20 +00:00

tahoe-lafs added this to the 1.12.0 milestone 2016-12-12 16:15:20 +00:00

Brian Warner <warner@lothar.com> commented

2016-12-12 21:57:53 +00:00

Author

Owner

In 1bb62d84/trunk:

tox docs: pin docutils-0.12

This avoids a bug in the recent docutils-0.13.1 which throws an exception
when encountering links to SVG images. ReadTheDocs currently does the same.
https://sourceforge.net/p/docutils/bugs/301/ is probably the upstream bug.

closes ticket:2847

In [1bb62d84/trunk](/tahoe-lafs/trac-2024-07-25/commit/1bb62d843f0d73091c58543224432e374d58d0c9): ``` tox docs: pin docutils-0.12 This avoids a bug in the recent docutils-0.13.1 which throws an exception when encountering links to SVG images. ReadTheDocs currently does the same. https://sourceforge.net/p/docutils/bugs/301/ is probably the upstream bug. closes ticket:2847 ```

tahoe-lafs added the

fixed

label 2016-12-12 21:57:53 +00:00

Brian Warner <warner@lothar.com> closed this issue

2016-12-12 21:57:53 +00:00