Opened 14 months ago

Closed 14 months ago

Last modified 8 months ago

#21869 closed Bug (fixed)

Documentation not building on Sphinx 1.2.1

Reported by: tragiclifestories Owned by: nobody
Component: Documentation Version: 1.6
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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'

Attachments (1)

sphinx-err-dGETXL.log (3.6 KB) - added by tragiclifestories 14 months ago.

Download all attachments as: .zip

Change History (9)

Changed 14 months ago by tragiclifestories

comment:1 Changed 14 months ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 14 months ago by Tim Graham <timograham@…>

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

In e1d18b9d2e8ac292940f070b0a8cb9733756acd9:

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

Thanks tragiclifestories for the report.

comment:3 Changed 14 months ago by 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

comment:4 Changed 14 months ago by 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

comment:5 Changed 14 months ago by 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

comment:6 Changed 14 months ago by timo

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.

comment:7 Changed 14 months ago by tragiclifestories

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.

comment:8 Changed 8 months ago by 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

Note: See TracTickets for help on using tickets.
Back to Top