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

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.

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?

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.

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?

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.

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

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

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)

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.

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

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.

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.

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.

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