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

New Issue

warner · 2016-12-12T16:15:20Z

warner commented

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

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.

warner added the

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

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

warner self-assigned this 2016-12-12 16:15:20 +00:00

Brian Warner <warner@lothar.com> commented

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

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

tahoe-lafs closed this issue

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

Sign in to join this conversation.