Add docutils 0.18 citation/footnote support using CSS grid (readthedocs#1381)

agjohnson · web-flow · commit a039e52ec587 · 2022-12-15T13:02:39.000+01:00
* Add docutils 0.18 citation/footnote support using CSS grid This is a fix for readthedocs#1322 that continues our pattern for HTML5 support using CSS grids, introduced for support for docutils < 0.17 HTML5 support. * Add lots of backreferences to a footnote * Drop brackets from footnote/citation links The brackets seem to be another docutils addition. * Tune grid display for Sphinx 4 and 5 Backrefs have a new styling that drops a lot of punctuation * Bump dependency on docutils to < 0.19 * Small tweak to footnote backrefs row span We don't want to use too large a value here, as some browsers might make explicit rows for us. We can't target -1 because the row count is implicit. * Revert some new styling and use nonbreaking backrefs for now * Downgrade tox * Use before pseudo class to break up backrefs consistently
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -14,7 +14,7 @@ commands:
         default: "17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest"
     steps:
       - checkout
-      - run: pip install --user tox
+      - run: pip install --user tox~=3.27
       - run: tox -e "<<parameters.version>>-sphinx{<<parameters.sphinx-version>>}"
   run-build:
     description: "Ensure built assets are up to date"
diff --git a/docs/demo/demo.rst b/docs/demo/demo.rst
@@ -27,16 +27,16 @@ text (generated by processing errors; this one is intentional).
 Also with ``sphinx.ext.autodoc``, which I use in the demo, I can link to :class:`test_py_module.test.Foo`.
 It will link you right to my code documentation for it.
 
-The default role for interpreted text is `Title Reference`.  Here are some explicit interpreted text roles:
+The default role for [1]_ interpreted text is `Title Reference`.  Here are some explicit interpreted text roles:
 a PEP reference (:PEP:`287`); an RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
 and explicit roles for :emphasis:`standard` :strong:`inline` :literal:`markup`.
 
 GUI labels are a useful way to indicate that :guilabel:`Some action` is to be taken by the user.
 The GUI label should not run over ``line-height`` so as not to :guilabel:`interfere` with text from adjacent lines.
 
-Key-bindings indicate that the read is to press a button on the keyboard or mouse,
+Key-bindings indicate that [1]_ the read is to press a button on the keyboard or mouse,
 for example :kbd:`MMB` and :kbd:`Shift-MMB`. Another useful markup to indicate a user action
-is to use ``menuselection`` this can be used to show short and long menus in software.
+is to use ``menuselection`` this [1]_ can [1]_ be [1]_ used [1]_ to [1]_ show [1]_ short [1]_ and long menus in software.
 For example, and ``menuselection`` can be seen here that breaks is too long to fit on this line.
 :menuselection:`My --> Software --> Some menu --> Some sub menu 1 --> sub menu 2`.
 
diff --git a/setup.cfg b/setup.cfg
@@ -45,7 +45,7 @@ packages = sphinx_rtd_theme
 python_requires = >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
 install_requires = 
 	sphinx >=1.6,<6
-	docutils <0.18
+	docutils <0.19
 tests_require = 
 	pytest
 
diff --git a/sphinx_rtd_theme/static/css/theme.css b/sphinx_rtd_theme/static/css/theme.css
diff --git a/src/sass/_theme_rst.sass b/src/sass/_theme_rst.sass
@@ -281,6 +281,8 @@
     top: -0.4em
     line-height: 0
     font-size: 90%
+    > span.fn-bracket
+      display: none
 
   // Horizontal lists have multiple columns; use full width
   .hlist
@@ -296,8 +298,9 @@
     display: none !important
 
   // The html4 writer outputs the citation and footnotes as a table, and the
-  // html5 writer outputs these as a definition list. We will use the fairly
-  // well supported css `grid` attribute to make these back into a table
+  // html5 writer outputs these as a definition list (docutils < 0.18) or an
+  // aside/div (docutils 0.18+). We will use the fairly well supported css
+  // `grid` attributes to make these back into a table
   // HTML4 writer
   html.writer-html4 &
     table.docutils.citation, table.docutils.footnote
@@ -313,13 +316,51 @@
         vertical-align: top
   // HTML5 writer
   html.writer-html5 &
+    // docutils < 0.18 grid layout. Some spacing is the dl/dt/dd margins
     dl.footnote, dl.citation, dl.field-list
       display: grid
-      grid-template-columns: max-content auto
+      grid-template-columns: auto minmax(80%, 95%)
+      > dt
+        display: inline-grid
+        grid-template-columns: max-content auto
+    // docutils => 0.18 grid layout
+    aside.footnote, aside.citation, div.citation
+      display: grid
+      // Two any width columns for label and backrefs, a noop column to expand
+      // to fill the width allocated to the first two columns, and then the
+      // content column for the paragraphs.
+      grid-template-columns: auto auto minmax(0.65rem, auto) minmax(40%, 95%)
+      & > span.label
+        grid-column-start: 1
+        grid-column-end: 2
+      & > span.backrefs
+        grid-column-start: 2
+        grid-column-end: 3
+        grid-row-start: 1
+        grid-row-end: 3
+      & > p
+        grid-column-start: 4
+        grid-column-end: 5
+
+    // Shared backrefs styling for docutils versions
+    @mixin footnote-backrefs
+      text-align: left
+      font-style: italic
+      margin-left: .65rem
+      word-break: break-word
+      word-spacing: -0.1rem
+      max-width: 5rem
+
+      > a
+        &:not(:first-child)::before
+          content: " " 
+        word-break: keep-all
+
+    // docutils < 0.18 html5 writer styling
+    dl.footnote, dl.citation, dl.field-list,
+      margin-bottom: $base-line-height
       > dt
         padding-left: 1rem
-        &:after
-          content: ":"
       > dt, > dd
         margin-bottom: 0rem
     dl.footnote, dl.citation
@@ -330,24 +371,45 @@
         word-break: break-all
         font-weight: normal
         > span.brackets
-          margin-right: 0.5rem
           &:before
             content: "["
           &:after
             content: "]"
         > span.fn-backref
-          font-style: italic
+          @include footnote-backrefs
       > dd
         margin: 0rem 0rem 0.5rem 0rem
         line-height: 1.2rem
         p
           font-size: 0.9rem
+
+    // docutils => 0.18 html5 writer styling
+    aside.footnote, aside.citation, div.citation
+      padding-left: 1rem
+      padding-right: 1rem
+      font-size: 0.9rem
+      line-height: 1.2rem
+      p
+        font-size: 0.9rem
+        line-height: 1.2rem
+        margin-bottom: $base-line-height / 2
+      span.backrefs
+        @include footnote-backrefs
+      span.label
+        line-height: 1.2rem
+    aside.footnote-list, aside.citation-list, div.citation-list
+      margin-bottom: $base-line-height
+
     dl.option-list
       kbd
         font-size: 0.9rem
   // Both
   html.writer-html4 & table.docutils.citation, table.docutils.footnote,
-  html.writer-html5 & dl.footnote, dl.citation
+  html.writer-html5 & dl.footnote,
+  html.writer-html5 & dl.citation,
+  html.writer-html5 & aside.footnote,
+  html.writer-html5 & aside.footnote-list aside.footnote,
+  html.writer-html5 & div.citation-list > div.citation
     color: $text-medium
     code
       color: $gray
