Documentation not building on Sphinx 1.2.1

[James Turley]

The latest release of Sphinx throws an AttributeError during the documentation build process. AttributeError: DjangoHTMLTranslator instance has no attribute 'optional_param_level'

To reproduce the error, just try to build the docs with Sphinx 1.2.1, into any format that requires a DjangoHTMLTranslator instance in the build process, obviously. (HTML, EPUB and JSON fail; LaTeX does not.)

I raise it here as it is already on the ​sphinx tracker: while resolved, the committer comments "Thanks for the report. This is not really a Sphinx issue (Django has to adapt their extension) but I pushed a fix that should make it work until they do."

I've tagged this as v1.6, but it also affects the master branch, where I ran into it in the first place.

pip freeze:

Django==1.6.1
Jinja2==2.7.2
MarkupSafe==0.18
Pygments==1.6
Sphinx==1.2.1
argparse==1.2.1
docutils==0.11
wsgiref==0.1.2

Terminal output on 'make html' (and other formats):

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  4%] howto/auth-remote-user                                 
Exception occurred:
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 153, in visit_desc_parameter
    if self.optional_param_level == 0:
AttributeError: DjangoHTMLTranslator instance has no attribute 'optional_param_level'
The full traceback has been saved in /tmp/sphinx-err-dGETXL.log, if you want to report the issue to the developers.

The trace in the logfile mentioned above:

Traceback (most recent call last):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 254, in main
    app.build(force_all, filenames)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/application.py", line 212, in build
    self.builder.build_update()
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 214, in build_update
    'out of date' % len(to_build))
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 276, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 320, in write
    self._write_serial(sorted(docnames), warnings)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 333, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/builders/html.py", line 433, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 51, in translate
    self.document.walkabout(visitor)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/home/filben/.virtualenvs/django-fixes/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 153, in visit_desc_parameter
    if self.optional_param_level == 0:
AttributeError: DjangoHTMLTranslator instance has no attribute 'optional_param_level'

[Tim Graham <timograham@…>]

In e1d18b9d2e8ac292940f070b0a8cb9733756acd9:

Fixed #21869 -- Fixed docs building with Sphinx 1.2.1.

Thanks tragiclifestories for the report.

[Tim Graham <timograham@…>]

In 85057522bc220585363e637528d970d3802475e8:

[1.4.x] Fixed #21869 -- Fixed docs building with Sphinx 1.2.1.

Thanks tragiclifestories for the report.

Backport of e1d18b9d2e from master

[Tim Graham <timograham@…>]

In e2e4de65551f152e20070bb42f1b4eb20feb0811:

[1.6.x] Fixed #21869 -- Fixed docs building with Sphinx 1.2.1.

Thanks tragiclifestories for the report.

Backport of e1d18b9d2e from master

[Tim Graham <timograham@…>]

In 60054e6e31abbe8ec17631f1afff77c947a05fad:

[1.5.x] Fixed #21869 -- Fixed docs building with Sphinx 1.2.1.

Thanks tragiclifestories for the report.

Backport of e1d18b9d2e from master

[Tim Graham]

Here's the sphinx change which causes the issue: ​https://bitbucket.org/birkenfeld/sphinx/commits/22c2e9bc9638

Basically we've overridden the visit_desc_parameterlist method to remove the <big> tags that Sphinx uses by default and each time the method changes we need to copy the changes. I'll update the ticket you created and ask if it would be possible to make the <big> tag configurable so we can remove this hack in our code.

[James Turley]

Interesting. It doesn't look like a huge change to Sphinx would be needed to pull that tag out to an attribute, but what do I know - I'm just the first newbie to try to build the docs since 1.2.1 went onto PyPI...

In the meantime, in case any confused soul googles their way here while trying to build the docs, it'll work if you specify Sphinx version 1.2.0, or if you clone the latest relevant branches of Sphinx or Django.

[Tim Graham <timograham@…>]

In 6726d750979a7c29e0dd866b4ea367eef7c8a420:

[1.3.x] Fixed #21869 -- Fixed docs building with Sphinx 1.2.1.

Thanks tragiclifestories for the report.

Backport of e1d18b9d2e from master