docutils 0.21.2 breaks the test suite

[kurtmckee]

docutils 0.20.1, installed in the Python 3.8 tox environment, matches test suite expectations.

docutils 0.21.2, installed in Python 3.9+ tox environments, breaks the test suite.

There appear to be small changes, like additional newlines, but also substantial differences, like this partial diff between what the test suite expected and what docutils 0.21.2 emitted:

- <nav class="contents" id="contents">\n<p class="topic-title">Contents</p>
+ <nav class="contents" id="contents">\n<p class="topic-title"><a href="#top" rel="nofollow">Contents</a></p>

As this isn't simply a whitespace change, I'm not currently pursuing a solution to this.

[miketheman]

Thanks for figuring that out.

While pinning to the older version will help pass the test suite, if we don't pin an upper bound to the package's dependency we'll get a different result from rendering the output (which might already be happening to folks today).

I think I'm more amenable to pushing forward with using the latest (and bumping the minimum version in pyproject.toml) and adapting the tests.

Python 3.8 EOL is in 4 months, I don't feel strongly that we need to preserve support for this library going forward.

[kurtmckee]

@miketheman Thanks for the feedback. To confirm, #311 could be closed in favor of a PR that:

• Drops support for Python 3.8
• Pins docutils to 0.21.x
• Updates the fixture files that render differently under the new docutils version

Does that match what you would expect from a PR that could close this issue?

[miketheman]

Yes, that seems to be a good list of items. When dropping 3.8 support, please also update the classifier list.

[kurtmckee]

@miketheman I opened #315 based on this feedback. If that PR looks good then #311 can be summarily closed. :+1: