Opened 8 years ago

Closed 8 years ago

#9645 closed (fixed)

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

Reported by: Walter Rodrigo de Sá Cruz Owned by: Ramiro Morales
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

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.

Attachments (5)

1.html (15.7 KB) - added by Walter Rodrigo de Sá Cruz 8 years ago.
Index generated with docutils == 0.4 and sphinx == 0.4.2 (it's ok)
2.html (16.6 KB) - added by Walter Rodrigo de Sá Cruz 8 years ago.
Index generated with docutils == 0.5 and sphinx == 0.4.2 (it's ok too)
3.html (16.3 KB) - added by Walter Rodrigo de Sá Cruz 8 years ago.
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)
4.html (15.4 KB) - added by Walter Rodrigo de Sá Cruz 8 years ago.
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.
t9645-r9523.diff (1.2 KB) - added by Ramiro Morales 8 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 Changed 8 years ago by 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.

comment:2 Changed 8 years ago by 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?

comment:3 Changed 8 years ago by 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.

comment:4 Changed 8 years ago by 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?

comment:5 Changed 8 years ago by 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.

Changed 8 years ago by Walter Rodrigo de Sá Cruz

Attachment: 1.html added

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

Changed 8 years ago by Walter Rodrigo de Sá Cruz

Attachment: 2.html added

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

Changed 8 years ago by Walter Rodrigo de Sá Cruz

Attachment: 3.html added

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)

Changed 8 years ago by Walter Rodrigo de Sá Cruz

Attachment: 4.html added

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.

comment:6 Changed 8 years ago by Walter Rodrigo de Sá Cruz

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

comment:7 Changed 8 years ago by Ramiro Morales

Owner: changed from nobody to Ramiro Morales
Version: 1.0SVN

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.

comment:8 in reply to:  7 Changed 8 years ago by Ramiro Morales

Has patch: set
Triage Stage: UnreviewedAccepted

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>
  1. 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.

Changed 8 years ago by Ramiro Morales

Attachment: t9645-r9523.diff added

comment:9 Changed 8 years ago by 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.

comment:10 Changed 8 years ago by Malcolm Tredinnick

Resolution: fixed
Status: newclosed

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

Note: See TracTickets for help on using tickets.
Back to Top