'tox -e docs' causes exception in docutils

[warner]

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.

[Brian Warner <warner@…>]

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