Opened 7 years ago

Closed 7 years ago

#9645 closed (fixed)

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

Reported by: waltercruz Owned by: ramiro
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 waltercruz 7 years ago.
Index generated with docutils == 0.4 and sphinx == 0.4.2 (it's ok)
2.html (16.6 KB) - added by waltercruz 7 years ago.
Index generated with docutils == 0.5 and sphinx == 0.4.2 (it's ok too)
3.html (16.3 KB) - added by waltercruz 7 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 waltercruz 7 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 7 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 Changed 7 years ago by mtredinnick

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

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 7 years ago by waltercruz

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 7 years ago by mtredinnick

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 7 years ago by mtredinnick

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 7 years ago by waltercruz

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 7 years ago by waltercruz

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

Changed 7 years ago by waltercruz

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

Changed 7 years ago by waltercruz

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 7 years ago by waltercruz

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 7 years ago by waltercruz

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

comment:7 follow-up: Changed 7 years ago by ramiro

  • Owner changed from nobody to ramiro
  • Version changed from 1.0 to SVN

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 7 years ago by ramiro

  • Has patch set
  • Triage Stage changed from Unreviewed to Accepted

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 7 years ago by ramiro

comment:9 Changed 7 years ago by waltercruz

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 7 years ago by mtredinnick

  • Resolution set to fixed
  • Status changed from new to closed

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

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