Reduce supported versions and release plan

[humitos]

While working a little on #1463 I found that this theme supports every single version from Sphinx 1.7 to 7.1, including HTML4 and HTML5 writers and Python 2.7 to 3.10. In my opinion, this is "great, but insane". The main point here is that we don't have enough time to support all these versions and we've been pretty blocked when trying to move forward even with small changes because it breaks in a weird way in some random old version or combination.

I want to propose reducing the matrix of supported versions to:

• Last 3 major Sphinx versions: 5.x, 6.x, 7.x
• Last 2 docutils versions supported by Sphinx: 0.19.x, 0.20.x
• Last 3 major Python versions: 3.9, 3.10, 3.11
• HTML5 only (Sphinx does not support HTML4 anymore since Sphinx 7: Remove HTML 4 support sphinx-doc/sphinx#11385)

This proposal will reduce the matrix a lot and also the complexity involved when testing and QAing. I think we have a good opportunity here to do a 2.0 release that removes all these new unsupported versions and start from fresh again aiming to recover some development pace by keeping things updated at least -- I'm not even talking about adding new features or similar.

Related:

• https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#supported-dependencies
• Add Sphinx 7 support #1463
• Support for docutils 0.19.x #1323
• Decision: Add to 2.x milestone? #1470
• Drop html4 testing, remove support for html4writer #1364
• Decide on release structure for backward incompatible changes #1086

[agjohnson]

We've talked about this a few times in the past already and have these deprecations started or already documented:

https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#roadmap

This is already close to our plan, though I don't think we should aim for all of these deprecations at once in a 2.0 release.

The main sources of pain are the HTML4 writer and Sphinx 1.x/2.x support, which we're already on the path to deprecate. But also the test matrix is just really large because we also have multiple browsers to test and multiple viewport sizes to test against.

Deprecations ongoing are:

• Since 1.0 HTML4 writer and direction installation through Git are deprecated. Removal of these will need to lead to throwing exceptions in future release though, as these are not pinnable dependencies.
• 2.0 hasn't happened yet, but the deprecations are listed here: https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#roadmap-release-2-0-0. We can definitely expand that more, but I think even Sphinx 3 is probably fine to include as the API hasn't changed too drastically after 2.x.

Python versions would be fine to cull, but these also do no introduce much testing complexity given the amount of Python here is really low. Modern Python is fine.

Docutils is more annoying, as it's transitive through Sphinx and can vary as it's not pinned there. I'd like to support mostly just the modern versions, but I don't think we can easily say "last X releases", we likely have more work to map this to what users are actually using.

The work to remove HTML4 support hasn't happened yet as it's a good chunk of work to remove the styles, and saying "we're not testing HTML4" is the biggest benefit. A 2.0 release could throw an exception on HTML4 writer usage, but keep the styles, but this isn't a huge net gain over where we are now either. The styles will remain hard to work with.

[agjohnson]

See also: #1086 which has a lot more conversation on the deprecations

[humitos]

This is already close to our plan, though I don't think we should aim for all of these deprecations at once in a 2.0 release.

What is blocking us from doing all these deprecation at once?

2.0 hasn't happened yet, but the deprecations are listed here: sphinx-rtd-theme.readthedocs.io/en/stable/development.html#roadmap-release-2-0-0. We can definitely expand that more, but I think even Sphinx 3 is probably fine to include as the API hasn't changed too drastically after 2.x.

We can adjust the work to keep the 2.0 as it was planned, and switch my proposal to be 3.0. I don't care about increasing the major version again after a few months of releasing 2.0. People will be able to keep using 1.2 if they are using old versions of Sphinx, docutils or similar. People using newer version of Sphinx will use 3.x and we won't need to care about old versions when working on 3.x.

Docutils is more annoying, as it's transitive through Sphinx and can vary as it's not pinned there. I'd like to support mostly just the modern versions, but I don't think we can easily say "last X releases", we likely have more work to map this to what users are actually using.

Sure, we can change my phrase here to adapt it as what we can realistically support.

[agjohnson]

What is blocking us from doing all these deprecation at once?

I'd say our roadmap priorities are blocking, and also that doing multiple hard deprecations simultaneously will incur more work than it's saving us right now.

Our roadmap priorities are still on the dashboard release and addons. Heavier development will pick up here afterwards, but we should keep up with RCs especially for cases like Sphinx 7 that don't affect our output much.

Multiple simultaneous deprecations are costly because there isn't guaranteed overlap between projects using outdated Python, outdated Sphinx, and the HTML4 writer. All of these are independent, though Sphinx is starting to reign these in with 7.0 ¹. For example, it's possible to use these old dependencies and not affect our output, and as of the Sphinx 6 release series, projects can still use Python 3.8, Sphinx 6, docutils 0.18.1 and the HTML4 writer.

Given we can't guarantee that projects are pinning our theme version, we can expect projects to randomly hit these deprecation exceptions, silent output failures, and resolver problems too I'm sure.

I think my preferred plan at this point is to release a 2.0 limiting Sphinx versions, and we do not specify a hard limit on Python or docutils (yet, or maybe ever). Eventually, as we bump up Sphinx versions, the bottom range of Python, docutils, and features like the HTML4 writer will start to match what we want to support. This also doesn't make for weird scenarios where our theme dependencies conflict with a valid set of Sphinx dependencies.

This is still a fairly sizeable win, we are still testing with old Sphinx releases still. Though, the bulk of the backwards incompatible changes usually come from docutils at some level. But Sphinx is going to be the most influential dependency, as this is the package that dictates versions downstream of docutils, Sphinx extensions, Jinja, etc. It's also the most common to be defined if projects define dependencies, docutils and transitive dependencies aren't commonly defined as we know.

Footnotes

1. For instance, the HTML4 writer support was finally removed in Sphinx 7: https://github.com/sphinx-doc/sphinx/blob/7.0.x/sphinx/builders/html/__init__.py#L1309-L1315 ↩

[ericholscher]

Call discussion: Release theme 2.0 with support for Sphinx 5 & above. Let the docutils and other dependencies be handled by Sphinx as a transitive dep.

[agjohnson]

And some download stats:

• Per major verison
• >=5 vs <5

Unsupported versions are about 33% of installs

[Jackenmen]

• Last 3 major Python versions: 3.9, 3.10, 3.11

Could that be made so that all non-EOL Python releases are supported? That means supporting 5 Python releases at any given time (it's 4 releases until 2023-10-02 because Python <3.8 had a different release cadence): https://devguide.python.org/versions/ At the current time, this specifically means including 3.8 since most Python libraries are expected to support non-EOL versions and will often build the documentation using the lowest supported Python version.

[agjohnson]

@Jackenmen We haven't updated the plan here to reflect all of our background conversation, but our plan at the moment is to rely on Sphinx to dictate the versions of dependencies that we'd support. So we'll support Sphinx 5+, which I think does mean we'd support 3.6+ and docutils 0.14+ (at least until we support Sphinx 6+).