Sphinx 6 is out and has important breaking changes¶
Important updates to this post ⬇️
sphinx-rtd-theme 1.2.0 has been released with support for Sphinx 6.
A necessary platform update on Read the Docs, released on February 7th 2023, allows for jQuery to be included in certain complex scenarios pertaining Sphinx 6.
Sphinx 6.1 has also been released with frequent patch releases. Be aware of open issues on the Sphinx GitHub project.
Sphinx 6 was released on December 29, 2022. It contains a few major breaking changes that users should be aware of, and some smaller new features as well. Here are some of our considerations for the upgrade process:
Python 3.8+ is required. To enable this on Read the Docs, you will need to specify a Python version using the build.tools.python setting. If it’s possible for your project, you can make the jump all the way to Python 3.11.
Support is dropped for docutils 0.14, 0.15, 0.16 and 0.17. It now supports only docutils 0.18 or 0.19.
sphinx-rtd-theme will support Sphinx 6 from 1.2.0, including docutils 0.18. You can already install the release candidate:
pip install sphinx-rtd-theme==1.2.0rc4.
For more information and full details you can read the Sphinx changelog
Since most documentation projects rely on themes and extensions, we recommend checking for Sphinx 6 support in those projects before upgrading.
Less maintenance work in the future¶
Sphinx 6 focuses on reducing the maintenance burden for the future. This is done by simplifying the factor of supported docutils versions and Python versions.
Moving forwards, the number of upgrade paths for documentation projects are fewer and thus will lead to less choices for documentation owners and maintainers of Sphinx themes and extensions. This is a positive step forward for both documentation projects, themes and extensions. If your Sphinx extensions and theme support Sphinx 6, we recommend this upgrade in order to reduce complexities and future technical debt.
Sphinx 6.0 and 6.1 are very fresh releases. As such, please remember:
Not all extensions and themes have added support for the new versions!
You may experience issues if you have not pinned your documentation dependencies.
Issues may also be caused by new bugs in the Sphinx 6 compatibility of extensions and themes. Visiting the issue trackers of these projects is helpful.
If you suspect that upgrade issues are caused by dependency mismatches, we recommend taking the approach of reproducible builds. This includes explicitly specifying all relevant dependencies. Read more in our documentation’s introduction to Reproducible Builds.
Don’t fancy upgrading?¶
A new release of Sphinx doesn’t mean an obligation to upgrade immediately. You can continue to use an older series of Sphinx such as 5.3.x, 4.5.x etc.
Environments compatible with older versions of Sphinx are supported on Read the Docs for many years, and Sphinx has a history of releasing updates for older series.