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
    self._indent.pop()
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.