Fix footnote styles to work with latest Sphinx + docutils

[jab]

What's happening?

A new version of Sphinx has now been released, which changes its dependency pins to allow docutils 0.19, which includes a fix for New HTML markup for footnotes is difficult to stylise, along with corresponding Sphinx changes.

Now that both Sphinx and docutils have made stable releases to address this issue, I believe Furo is no longer blocked from writing styles that fix the regression in footnote alignment that was caused by the changes in docutils 0.18. (The latest version of Furo is still causing the broken looking footnotes that are visible in this screenshot when used with latest Sphinx (5.1.1) and docutils (0.19).)

Reproducer

1. Build Sphinx documentation at https://github.com/jab/bidict by running pip install -r requirements/docs.txt && make -C docs html from a fresh clone.
2. Open docs/_build/html/index.html in a browser.
3. Scroll down to the footnotes at the bottom of the page.
4. Observe that (1) footnotes are no longer appearing on the same line as their corresponding footnote numbers, and (2), they're not even being indented consistently: Note how footnote 3 is not indented, while footnotes 1, 2, and 4 are indented:

Ref: #452

Expectation

Alignment of footnotes stays consistent and correct, as it appeared before the changes introduced in docutils 0.18 caused this breakage:

Code of Conduct

• I agree to follow the Code of Conduct.

[jab]

Hi @pradyunsg, I see you converted the issue created for this into this discussion.

Just wanted to explain that I created an issue rather than a discussion because we already had a prior discussion about this in #452, and I interpreted your much-appreciated response there and your followup reporting to the Sphinx and docutils projects as acknowledgment that you would welcome a trackable issue for this, now that there is an unblocked piece of work that would fix this in Furo, when used with recent enough Sphinx + docutils. I'm sorry I misunderstood, and I hope you don't mind.

If there are any other thoughts you can share to clarify this issue, I'd be grateful to understand better. Thanks again for all your great work on Furo and in the community in general.

[jab]

@pradyunsg, I followed https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html#adding-custom-css-or-javascript-to-sphinx-documentation to work around this in a custom.css file. If my workaround generalizes, then the following patch to Furo would fix this:

diff --git a/src/furo/assets/styles/content/_footnotes.sass b/src/furo/assets/styles/content/_footnotes.sass
index 608f895d..4afdd721 100644
--- a/src/furo/assets/styles/content/_footnotes.sass
+++ b/src/furo/assets/styles/content/_footnotes.sass
@@ -40,4 +40,5 @@ div.citation > span

 aside.footnote > p,
 div.citation > p
-  margin-left: 2rem
+  margin-left: 1rem
+  display: inline-block

Would you be willing to give this two-line change a try with one of your projects that uses footnotes, and if all looks good to you, apply the changes?

[jab]

Thanks for getting back to me on this!

I tried make my window narrower so that one of my footnotes becomes multi-line, and this is still strictly an improvement over the current styles:

Before narrowing:

After narrowing:

Compare these to the first screenshot in my initial post in this discussion and I think you'll see what I mean.

Would you be willing to accept these changes as an incremental improvement?

[pradyunsg]

Try making that change, and looking at the footnotes section in kitchen-sink/generic/ -- the multi-paragraph footnotes will render in a suboptimal manner.

[jab]

Ah, with a multi-paragraph footnote (not just multi-line) I see what you mean, thanks.

Here's another approach:

diff --git a/src/furo/assets/styles/content/_footnotes.sass b/src/furo/assets/styles/content/_footnotes.sass
index 608f895d..028e0499 100644
--- a/src/furo/assets/styles/content/_footnotes.sass
+++ b/src/furo/assets/styles/content/_footnotes.sass
@@ -36,7 +36,9 @@ aside.footnote
 
 aside.footnote > span,
 div.citation > span
+  float: left
   font-weight: 500
+  padding-right: 0.25rem
 
 aside.footnote > p,
 div.citation > p

And here's what the kitchen sink footnotes look like with this applied:

What do you think?

[pradyunsg]

You know what, sure -- could you file a PR for this?

[jab]

Sure, submitted #576. PTAL and thanks for your consideration.