[tahoe-lafs-trac-stream] [Tahoe-LAFS] #2847: 'tox -e docs' causes exception in docutils

[Tahoe-LAFS]

#2847: 'tox -e docs' causes exception in docutils
---------------------------+------------------------
 Reporter:  warner         |          Owner:  warner
     Type:  defect         |         Status:  new
 Priority:  normal         |      Milestone:  1.12.0
Component:  documentation  |        Version:  1.11.0
 Keywords:                 |  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 ([https://sourceforge.net/p/docutils/bugs/301/
 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.

--
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2847>
Tahoe-LAFS <https://Tahoe-LAFS.org>
secure decentralized storage