Overview

This is a ticket to discuss the best way to pin dependencies for Sphinx. The current status appears to be the latest Sphinx 3.x and 4.x release is pinning docutils<0.17. This will work around the existing changes in docutils until they can be tested (#9088).

This raises the question of other dependencies that might change HTML output and break users experience with Sphinx. I can think of two major categories of these changes:

• Direct dependencies that change HTML output (eg. pygments & docutils)
• Transitive dependencies that have the same outcome (I don't know what these would be, but they likely exist)

Direct Dependencies

In terms of direct dependencies, I think we probably want to pin to the latest minor version (eg. <2.9 for Pygments, which is currently at 2.8.1). This will handle most of the obvious issues.

Transitive Dependencies

The trickier thing is what to do with transitive dependencies. I think there are two options here:

1. We can work with our dependencies to pin their dependencies (and so on down the chain :D)
2. We can research the obvious things that might break (have any broken in the past?) and pin them directly on Sphinx

I think we should opt for #1, but do #2 as a backup if needed.

Next Steps

Since we currently have docutils pinned, we need to see what other Sphinx dependencies need to be pinned, and work to get those first. Anything that we pin, we need to make sure we have a process for testing changes to and upgrading them with releases, so we need to work alongisde #9088 on this process.