Bug 850551 - Sphinx manpage generation is broken with the new docutils package
Sphinx manpage generation is broken with the new docutils package
Product: Fedora
Classification: Fedora
Component: python-sphinx (Show other bugs)
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: Michel Alexandre Salim
Fedora Extras Quality Assurance
Depends On:
  Show dependency treegraph
Reported: 2012-08-21 16:03 EDT by Toshio Ernie Kuratomi
Modified: 2012-09-17 18:25 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2012-09-17 18:25:37 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)
Patch to add sphinx admonition labels instead of overriding visit_admonition() (1.22 KB, patch)
2012-08-21 16:03 EDT, Toshio Ernie Kuratomi
no flags Details | Diff

  None (edit)
Description Toshio Ernie Kuratomi 2012-08-21 16:03:43 EDT
Created attachment 606036 [details]
Patch to add sphinx admonition labels instead of overriding visit_admonition()

Description of problem:
In the new docutils version (0.10 -- we're currently shipping a snapshot) there's a change to the manpage writer.  Part of that change increments the indent level when visit_admonition() is called and decrements the indent level when depart_admonition() is called.

Sphinx has its own manpage writer that customizes several aspects of the docutils manpage writer.  One of those is to override visit_admonition() to add some new labels for admonitions.  However, they do not also override depart_admonition().  This leads to a problem with the new version of docutils where the indent level is decremented past the top level leading to a traceback:

  File "/usr/lib/python2.7/site-packages/docutils/writers/manpage.py", line 877, in dedent
IndexError: pop from empty list

There's two ways that I see to rework this.

* override depart_admonition() as well.
* Instead of overriding visit_admonition(), add the additional labels to the data structure that docutils.writers.manpage will use.

I'll attach a patch to do the latter that I am also sending upstream.

We'll need to apply this in F18 and F19.  Note: At this time python-docutils is not able to rebuild for python3-3.3 so we're not able to build anything that depends on it (including pyhton-sphinx).  We have to wait on resoultion to that before we can push this fix out.
Comment 2 Luke Macken 2012-08-21 16:57:32 EDT
I tested the patch locally and it fixes the issue that I'm seeing the with building pyrasite's docs on F18 and newer.
Comment 3 Fedora Update System 2012-08-25 11:03:26 EDT
python-sphinx-1.1.3-5.fc18 has been submitted as an update for Fedora 18.
Comment 4 Fedora Update System 2012-08-25 14:20:04 EDT
Package python-sphinx-1.1.3-5.fc18:
* should fix your issue,
* was pushed to the Fedora 18 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing python-sphinx-1.1.3-5.fc18'
as soon as you are able to.
Please go to the following url:
then log in and leave karma (feedback).
Comment 5 Fedora Update System 2012-09-17 18:25:37 EDT
python-sphinx-1.1.3-5.fc18 has been pushed to the Fedora 18 stable repository.  If problems still persist, please make note of it in this bug report.

Note You need to log in before you can comment on or make changes to this bug.