Opened 15 years ago

Closed 15 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: dev
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

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 15 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 15 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 15 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 15 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 15 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 by Malcolm Tredinnick, 15 years ago

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 by Walter Rodrigo de Sá Cruz, 15 years ago

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 by Malcolm Tredinnick, 15 years ago

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 by Malcolm Tredinnick, 15 years ago

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 by Walter Rodrigo de Sá Cruz, 15 years ago

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.

by Walter Rodrigo de Sá Cruz, 15 years ago

Attachment: 1.html added

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

by Walter Rodrigo de Sá Cruz, 15 years ago

Attachment: 2.html added

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

by Walter Rodrigo de Sá Cruz, 15 years ago

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)

by Walter Rodrigo de Sá Cruz, 15 years ago

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 by Walter Rodrigo de Sá Cruz, 15 years ago

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

comment:7 by Ramiro Morales, 15 years ago

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.

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

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.

by Ramiro Morales, 15 years ago

Attachment: t9645-r9523.diff added

comment:9 by Walter Rodrigo de Sá Cruz, 15 years ago

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 by Malcolm Tredinnick, 15 years ago

Resolution: fixed
Status: newclosed

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

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