Docutils 0.17 breaks the captions

[jorisvandenbossche]

Tests on master fail, and the difference is docutils bumped from 0.16 to 0.17. Output of a failing test:

 E       AssertionError: FILES DIFFER:
E       /tmp/pytest-of-runner/pytest-0/test_sidebars_captions0/test_build/test_sidebars_captions.html
E       /tmp/pytest-of-runner/pytest-0/test_sidebars_captions0/test_build/test_sidebars_captions.obtained.html
E       HTML DIFF: /tmp/pytest-of-runner/pytest-0/test_sidebars_captions0/test_build/test_sidebars_captions.obtained.diff.html
E       --- 
E       +++ 
E       @@ -1,6 +1,6 @@
E        <nav aria-label="Main navigation" class="bd-links" id="bd-docs-nav">
E         <div class="bd-toc-item active">
E       -  <p class="caption">
E       +  <p>
E           <span class="caption-text">
E            Section 1
E           </span>

So the "caption" class is gone now. This can also be seen in the unstyled output of those captions in the latest docs (will pin docutils to fix this for now)

[jorisvandenbossche]

Relevant sphinx issue: sphinx-doc/sphinx#9051

[jorisvandenbossche]

As noted in the sphinx issue (sphinx-doc/sphinx#9051), there might also be other CSS broken (eg <div class="section", id=".."> changed into <section id="..">, which might needs different CSS selectors)

[vale981]

sphinx-doc/sphinx#9051
appears to be fixed,
can the pin be removed then?

[jorisvandenbossche]

Indeed, thanks for the ping about it.

Although it still depends on the sphinx version you have (but we probably shouldn't care about that?)

[astrojuanlu]

If I understand correctly, this would still be broken in docutils 0.17 and Sphinx < 4.0.0. However, forcing Sphinx~=4.0 might be premature, since there are still some extensions that are not compatible with it. Just FYI (I don't know what's pydata-sphinx-theme attitude or policy towards dependencies)

[jorisvandenbossche]

It seems that sphinx 3.x added a pin for docutils (sphinx-doc/sphinx#9071), so that's a case we should not worry about