Sphinx: Smart quotes cause Sphinx to crash inside docutils

[arximboldi]

Problem

When building the documentation in https://github.com/arximboldi/immer with a recent version, the build fails.

Note: I did find the offending commit: edc7f30b9cc92f4d721eeef62ffa826f23a09a9f
Reverting it solves the problem.

Procedure to reproduce the problem

Checkout the code from the linked repository, install Sphinx from master and build the documentation.

Error logs / results

Error log here: https://gist.github.com/arximboldi/12c0956324be2cd70d93a60782524f32

Reproducible project / your project

https://github.com/arximboldi/immer

Environment info

• OS: Debian Linux
• Python version: Python 2.7.13
• Sphinx version: Master
• Docutils: 0.13.1

[jfbu]

Thanks for the report and trying out on master.

But I had a quick look checking out your project, but I am not familiar with doxygen, so I skipped it, and I get no build error of this type whether using Sphinx 1.5.5, or the current stable branch or the 1.6-release branch, or the master branch.

# Sphinx version: 1.5.5 (or stable, or 1.6-release, or master)
# Python version: 2.7.13 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.9.6

Your report says Docutils: 0.13.1 but the error log at gist says

# Docutils version: 0.12 release

at https://gist.github.com/arximboldi/12c0956324be2cd70d93a60782524f32#file-sphinx-err-35dmlq-log-L3

can you check your docutils version ?

[jfbu]

I tested with on master with both Docutils 0.11 and 0.12 and do not reproduce the error, but this is all without the doc/_doxygen/xml/index.xml file.

[arximboldi]

Ooops, sorry I pasted an older error log... here is another log with the latest Docutils:
https://gist.github.com/arximboldi/345b83a695a0150315e37ef6db56c8c1

Thanks for trying my code! The project actually needs doxygen to generate any meaningful and thus trigger the issue. Here is what you should do to build the documentation:

1. Install doxygen and cmake (e.g. via apt-get, brew, etc..)
2. Go to the project root and then:

mkdir build; cd build
cmake ..
make docs

That last command will first run doxygen and then sphinx. When using the current sphinx master (or any branch containing the aforementioned commit) it fails for me.

[jfbu]

ah ok, I know how to use doxygen now... and I reproduce the error you reported with all version docutils 0.11, 0.12, and also 0.13.1... (on Sphinx master)

(I can't look any deeper right now)

[tk0miya]

It's bug of breathe.
The extension builds doctree with wrong way.
https://github.com/michaeljones/breathe/blob/d3eae7fac4d2ead062070fd149ec8bf839f74ed5/breathe/renderer/sphinxrenderer.py#L1103

This code rewrites directly the children attribute of the nodelist[0]. As a result, the structure of doctree has broken (In detail, the child nodes of nodelist[0] does not refer nodelist[0] as a parent). That causes this problem.
The docutils clients have to use the methods of docutils.node.Element. It
In this case, using Element.insert() works well:

        if nodelist:
            # nodelist[0].children = [term, separator] + nodelist[0].children
            nodelist[0].insert(0, term)
            nodelist[0].insert(1, separator)
        else:
            nodelist = [term]

Please report this to breathe project please.

[arximboldi]

Wow, that was an quick and excellent debugging. Thanks a lot!