#2847 closed defect (fixed)

'tox -e docs' causes exception in docutils

Reported by: warner Owned by: warner
Priority: normal Milestone: 1.12.0
Component: documentation Version: 1.11.0
Keywords: Cc:
Launchpad Bug:


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.

Change History (1)

comment:1 Changed at 2016-12-12T21:57:53Z by Brian Warner <warner@…>

  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.