Documentation generated with docutils 0.4 has broken css due to broken ids

[Walter Rodrigo de Sá Cruz]

Hi!

When generating the django docs with docutils 0.4, some css classes get broken. What happens is that docutils -0.5 generate the div ids as "s-getting-help" and 0.4 generates these id just as "getting-help". So, some minor css get broken when generating css with docutils 0.4. Docutils 0.4 is still present in a lot of distros.

[Malcolm Tredinnick]

I cannot repeat this problem with docutils-0.4, at least as installed on my system (and it doesn't look like Fedora have made any significant patches that will have changed). Sadly, the docutils page at sourceforge doesn't seem to provide any way to download the vanilla 0.4 tarball, so I can't confirm it one way or the other.

I think this might turn out to be a case of "we can't support everything", but it would be nice to know why somebody is seeing an issue with 0.4 and somebody else (me) isn't.

[Walter Rodrigo de Sá Cruz]

You can install docutils 0.4 using easy_install easy_install docutils==0.4 . You can do it in a virtualenv. How can I send you more docs and tests ? What kind of docs and tests do you need?

[Malcolm Tredinnick]

I'm not about to run "easy_install" anything on my system, but I'd forgotten it might be hanging around on PyPI. I grabbed the tarball from there and will see what washes out. Thanks.

[Malcolm Tredinnick]

So, I've confirmed that the problem doesn't occur for me with the vanilla docutils-0.4 tarball (in fact, there's no significant different between that and what Fedora 8 ships). So it's not docutils doing this.

What version of Sphinx are you using to generate the documentation?

[Walter Rodrigo de Sá Cruz]

Hi! I tried to do betters tests :)

The issues looks to be the combination of docutils 0.4 and sphinx 0.4.2 . I will try to find more info.

[Walter Rodrigo de Sá Cruz]

Index generated with docutils == 0.4 and sphinx == 0.4.2 (it's ok)

[Walter Rodrigo de Sá Cruz]

Index generated with docutils == 0.5 and sphinx == 0.4.2 (it's ok too)

[Walter Rodrigo de Sá Cruz]

Index generated with docutils == 0.5 and sphinx == 0.4.3 (the div with id s-getting-help is ok, but the href to #getting-help is broken (there's no anchor with such id)

[Walter Rodrigo de Sá Cruz]

Index generated with docutils == 0.4 and sphinx == 0.4.3. There's no div with id s-getting-help (The css will be broken) but the anchor href="#getting-help" will work.

[Walter Rodrigo de Sá Cruz]

I have added 4 files that I have generated with different versions of docutils and sphinx.

[Ramiro Morales]

See

1. ​Sphinx bug report
2. Sphinx 0.4.x branch ​changeset and ​relevant diff, this change was included in Sphinx release 0.4.3
3. Related(?) Django doc builder ​workaround

FWIW the modification in item 2 above was immediately ​ported to Sphinx trunk so issue will also be present with unreleased Sphinx 0.5. I cat reproduce this with a recent Sphinx trunk checkout plus docutils 0.5.

[Ramiro Morales]

Replying to ramiro:

I cat reproduce this with a recent Sphinx trunk checkout plus docutils 0.5.

I meant I CAN reproduce this.... BTW Sphinx 0.5 was released today.

I'm attaching a patch that tries to ensure that the doc building process:

1. Creates the "s-"-prefixed section id names as per Django original styling requirements. Example:

   <div class="section" id="s-getting-help">
   

2. Creates and preserves the anchor names associated the section titles so the docs.djangoproject.com URLs don't change (links pointing to internal sections already in the wild will keep working). It does so by means of an id attribute, either in an empty <span> tag or in the <hN> tag itself. Examples:

(Sphinx 0.5, docutils 0.5):

<span id="getting-help"></span><h2>Getting help<a class="headerlink" href="#getting-help" title="Permalink to this headline">¶</a></h2>

(Sphinx 0.4.2, docutils 0.5):

<h2 id="getting-help">Getting help<a class="headerlink" href="#getting-help" title="Permalink to this headline">¶</a></h2>

3. Both requirements above are met also with locally generated HTML documentation so styling and navigation don't get broken.

I have tested it in the six possible scenarios: Sphinx versions 0.4.2, 0.4.3 & 0.5 and docutils versions 0.4 & 0,5. Please test it in your local environment.

[Walter Rodrigo de Sá Cruz]

Ok, I have tested with the six possible scenarios (Sphinx versions 0.4.2, 0.4.3 & 0.5 and docutils versions 0.4 & 0,5.) and its all ok.

[Malcolm Tredinnick]

Fixed in r9586 (trunk) and r9587 (1.0.X).