Fix rendering of footnotes and citations for Sphinx 2

[jessetan]

Sphinx 2 uses definition lists for footnotes and citations instead of tables, yay!
The existing theme CSS undid most of the default styling wyrm applied to tables so footnotes looked better. I've added similar styles for Sphinx 2. The rendering for Sphinx < 2 is unaffected.

There are minor visual differences, review is appreciated.

Sphinx <2:

Sphinx >2:

Differences:

• back references (the (1,2) links) are not aligned with the footnote text due to different DOM structure. I do not consider this an issue
• Footnote text does not start on same line as label. This is less compact and I'm not sure it takes up too much space. It is also harder to fix nicely with a consistent look for footnotes with and without a back reference. Note the inconsistency between footnote 1 and 2 in the previous situation

Fixes #741

[agjohnson]

I took a different approach with this, using flex:

However, it's flex, which is not a great application for converting lists into tables. But it's not playing around with floats at least. Is the tabular display of footnotes something worth preserving?

One area that it doesn't look correct, because it's sized proportionally:

[rkwestel]

Is there a reason footnotes were changed from tables to definition lists? Even if you change the styling via CSS to get rid of the ugly background and border, short of jumping through flex hoops as @agjohnson shows, you're still stuck with the disconnected presentation of a footnote number with its associated content on the next line; it looks terrible and takes up way more space than necessary. This provokes my distaste for markup languages that presume to know what you want and often get it wrong.

[agjohnson]

Sphinx 2 uses it's HTML 5 writer by default, which outputs definition lists. Sphinx < 2 uses the HTML 4 writer by default, which use a table output for footnotes.

[polyzen]

Perhaps this is a regression or they have a good reason for this.

[rkwestel]

Perhaps this is a regression or they have a good reason for this.

Perhaps, but I fail to see one. I'm advocating for dropping the use of footnotes altogether, or hand-coding them with embedded html, which defeats the purpose of markup to begin with. <insert "disappointed" emoji here>

[rkwestel]

On a positive note, I just found this and will try the various suggestions until I find one that works for us: https://stackoverflow.com/questions/1713048/how-to-style-dt-and-dd-so-they-are-on-the-same-line/21261303#21261303

This solution is the simplest and works like a charm (coupled with a bit of additional CSS to clean up the margin, padding, line-height, and font-size of the various elements to get everything to line up the way I wanted):

dl {
  display: grid;
  grid-template-columns: max-content auto;
}

dt {
  grid-column-start: 1;
}

dd {
  grid-column-start: 2;
}

[agjohnson]

That is the ideal CSS fix, however grid-column-start is not supported by the browsers that we support, it's a relatively new feature.

I think that the most compatible way that we can address this is to override the writer being used by the builder and output a more helpful structure. For now, a fix like this PR presents the least number of issues and doesn't harshly affect display.

[jessetan]

Is the tabular display of footnotes something worth preserving?

@agjohnson I would be OK with dropping the tabular (it's what sphinx does after all), hence my PR. Floats and flex have the annoying habit to produce corner cases that look completely off.

[Blendify]

That is the ideal CSS fix, however grid-column-start is not supported by the browsers that we support, it's a relatively new feature.

I think that the most compatible way that we can address this is to override the writer being used by the builder and output a more helpful structure. For now, a fix like this PR presents the least number of issues and doesn't harshly affect display.

@agjohnson do you approve this PR?

[agjohnson]

I think I've come around to CSS grid. While flex worked, there were edge cases that I hit. The fallback from CSS grid looks similar to the results above, so it would be mostly safe.

The fixes are in #838, which supersedes the need for this PR

[Blendify]

I think we can agree on using #838 as a proper fix here.