feat(docutils): Use `section_self_link` (needs html5 + CSS update)

[erikmd]

I recently noticed that despite the availability of this new feature in docutils: https://sourceforge.net/p/docutils/feature-requests/28/ (which BTW can only be enabled in HTML5), the feature requested in cpitclaudel/alectryon#19 was not yet possible in alectryon.

So, this PR makes it possible to benefit from this feature in Alectryon as well by default.

Cc @cpitclaudel

[erikmd]

Here is a screenshot of what we can expect:

[erikmd]

On second thought, it seems with this current PR version, the user would need to write a ./docutils.conf with:

[html5 writer]
section_self_link: yes

@cpitclaudel What source file should be edited in alectryon to make this option a default? (if you don't disagree to do so (but I don't see any drawback that it could cause))

[cpitclaudel]

Thanks, looks good! Two questions:

• Do we really want to change the default to html5? I think it's OK for people to pick that manually. There's a command line flag for it.

• Did you take the CSS from the default stylesheet?

What source file should be edited in alectryon to make this option a default?

Should we make it the default? I'd prefer to not deviate too much from plain docutils. If we must it can be done in docutils.py, in the custom writer inherited from html5writer, I think. The advantage of doing it there is that it can still be overwritten by a setting.

[erikmd]

Hi @cpitclaudel

Do we really want to change the default to html5?

IMHO, I'd vote for it. Indeed:

• Nowadays, HTML5 is definitely the recommended DOCTYPE by the main web frameworks; supported by all browsers;
• If we are interested in having section_self_link the default (see below), using the html5 writer is the only requirement AFAIK.

Did you take the CSS from the default stylesheet?

Yes! but I improved it a bit → adding the text-decoration:none element to ensure there's no ugly bar below the anchor 🔗.

Should we make it the default? I'd prefer to not deviate too much from plain docutils.

OK, I see what you mean, but:

• I wouldn't see this new feature as a "non backward-compatible change"… the impact on the output is limited.
• Still, it is useful and really "standard" (e.g., I believe this kind of feature is builtin in Sphinx, while it was just non-available in docutils… before we opened this feature request in Sourceforge :)
• And finally I believe that most users interested in this feature would prefer to have an "opt-out" rather than an "opt-in"
  (so of course it would be sensible to provide some option to disable it (or just overwrite it with a setting as you said), but if I convinced you… I guess it'd be really great if it is on by default :)

However, regarding the implementation, I'm not sure I could extend/refine this PR as quickly as you could… so let me know if you don't have time and I'll try to push new commits at some point, otherwise feel free to amend my PR! (using git prw or so for example, or opening a new PR)

[erikmd]

@cpitclaudel friendly ping :) WDYT?

[erikmd]

Hi @cpitclaudel, how are you? would you have the time to help integrating this contribution?

AFAIAC, this will be a very important enhancement for our Alectryon-based courses.

[cpitclaudel]

Hi @erikmd, sorry for the delay :'(

Here's the issue: docutils HTML5 compiler does a lot of things differently from the HTML4 one, so people who just recompile an existing document with custom stylesheets will see breakage. I don't know when/whether docutils will switch, but I'm not sure we should until they do.

You say it will enhance courses, but why not use it already? IIUC all you need is to add the additional flag and add the short CSS to your own stylesheets?

Sorry if I missed something (and sorry I took so look to reply)

[erikmd]

Hi @cpitclaudel, no worries and thanks for your reply!

Some thoughts:

• IMHO the feature to automatically insert self links in the html output is a must-have in a tool such as Alectryon
• the fact that it isn't available yet out-of-the-box because it requires html5 but docutils defaults to html4 (whose W3C standard dates back to 1999) looks like a technical detail
• actually I'm not sure I understood your sentence "people who just recompile an existing document with custom stylesheets will see breakage", which breakage do you mean?

[erikmd]

You say it will enhance courses, but why not use it already? IIUC all you need is to add the additional flag and add the short CSS to your own stylesheets?

that's a good point :) but we did so already:

https://github.com/pfitaxel/tapfa-coq-alectryon/blob/master/docutils.conf

[erikmd]

so the main goal of this PR was to let more users to benefit from this feature… including users that are not aware of the docutils internals.

And even I agree with you that backward-compatibility is paramount, I guess this PR (which is incomplete BTW, so in draft mode, cf. this comment) should not incur "regressions"… WDYT?

[erikmd]

ping @cpitclaudel, would you have some time to help me improve/finalize this PR if you agree with my last comments?

[cpitclaudel]

Sorry, I had lost track of this. So there are three things here:

• Including CSS in docutils_basic to display the self-link. I like that; it's not great that our docutils_basic is diverging, though. Perhaps we could even upstream that change.
• Changing the default value. I'm not sure: shouldn't this happen upstream? But to do it here you'd modify the settings_default_overrides in HtmlWriter in docutils.py (ideally only for HTML5 I think)
• Changing to HTML5 by default: that scares me.