Currently, our documentation builds using Sphinx v5.3.0 and docutils 0.16. Originally, this related to a formatting dependency when using Python 3.7. Since the repository has set Python 3.9 as the minimum, the Sphinx and docutils can be upgraded to more recent versions without causing the formatting issues we were previously seeing.
Solution
Upgrade Sphinx to at least v6.0.0 and docutils to a compatible version. To ensure that documentation dependencies stay in-sync, we can use a requirements.in file to specify a minimum version of Sphinx, and then pip-tools can generate a requirements.txt file that takes into account all dependencies listed in requirements.in. This avoids the guess-and-check and only-update-when-broken approaches from the past. We can periodically reassess whether the Sphinx version should be upgraded and then regenerate requirements.in with all of the dependencies.
Description
Currently, our documentation builds using Sphinx v5.3.0 and docutils 0.16. Originally, this related to a formatting dependency when using Python 3.7. Since the repository has set Python 3.9 as the minimum, the Sphinx and docutils can be upgraded to more recent versions without causing the formatting issues we were previously seeing.
Solution
Upgrade Sphinx to at least v6.0.0 and docutils to a compatible version. To ensure that documentation dependencies stay in-sync, we can use a
requirements.infile to specify a minimum version of Sphinx, and thenpip-toolscan generate arequirements.txtfile that takes into account all dependencies listed inrequirements.in. This avoids the guess-and-check and only-update-when-broken approaches from the past. We can periodically reassess whether the Sphinx version should be upgraded and then regeneraterequirements.inwith all of the dependencies.