Sphinx 5 + Docutils 0.18 generates difficult to stylise markup for footnotes

[pradyunsg]

Describe the bug

With docutils 0.18, the markup generated for footnotes is difficult to stylise in a manner consistent with docutils 0.17. Since Sphinx 5 allows the use of docutils 0.18, this means that Sphinx themes have to now try to work with this more-difficult-to-stylise-consistently markup.

How to Reproduce

• Pick any Sphinx 5 documentation set with footnotes. ¹
• Generate the documentation with docutils 0.17 in an output directory.
• Generate the documentation with docutils 0.18 in a different output directory.
• Compare the footnote markup between 0.17 vs 0.18 -- notice the changes and the lack of grouping of multiple paragraphs.

Expected behavior

The markup would not change in Sphinx 5, preserving the same grouping as Sphinx 4 had permitted. Or, it would group the label + backref in a div and the paragraphs in a separate div, similar to the dd + dt style of Sphinx 4.

Your project

https://github.com/pradyunsg/furo/

Screenshots

No response

OS

N/A

Python version

N/A

Sphinx version

5.x

Sphinx extensions

No response

Extra tools

No response

Additional context

I've filed https://sourceforge.net/p/docutils/bugs/450/ for this, in docutils. I'm filing this to partly flag this issue/concern to Sphinx's maintainers/contributors as well as other theme authors. :)

Footnotes

1. The following markup in a .rst file is sufficient to reproduce this:

   Footnotes Demonstration
   =======================
   
   .. [1] A footnote contains body elements, consistently indented by at
      least 3 spaces.
   
      This is the footnote's second paragraph.
   
   .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
      automatically using a "#"-prefixed label.  This footnote has a
      label so it can be referred to from multiple places, both as a
      footnote reference ([#label]_) and as a hyperlink reference
      (label_).
   

   You can probably get away with an empty conf.py file. ↩

[AA-Turner]

@pradyunsg -- c6e1964 was my attempt to fix this from a CSS perspective in Sphinx, although I agree with you on the root cause.

I've uploaded a patch on bugs#450 that would resolve this, although (to my knowledge) there's no timeline yet on Docutils 0.19.

A

[jab]

Looks like https://sourceforge.net/p/docutils/bugs/450/ has been fixed, yay. Are any followup changes necessary in Furo and/or Sphinx? I'm just a Furo + Sphinx user following along here and wanting to make sure I'm tracking any necessary followup work so I know when it's safe to upgrade again. Thanks for the great work on these awesome projects!

[AA-Turner]

Docutils 0.19 will be released early July, all being well. The earliest Sphinx that would support it would be 5.1 most likely, and after that Furo would need to be updated.

We could also probably add a patch in Sphinx for Docutils==0.18 to use the 0.19 behaviour - I might have time to work on this over the weekend. (If I remember!)

A

[pradyunsg]

Any way for me to test the fix? I'm not sure how to get the patched in-development sources from SourceForge. :/

[AA-Turner]

See the Docutils HEAD job in tox.ini (used by the weekly workflow)

Edit: run python -m pip install "git+https://repo.or.cz/docutils.git#subdirectory=docutils"

A

[jab]

Thanks, @AA-Turner! Will keep following this issue for updates (along with any new issues or PRs I see referencing this issue). Look forward to upgrading once this is fixed.

[AA-Turner]

See also #10599

A

[AA-Turner]

Closed by #10599 and Docutils changes.

A