https://blog.readthedocs.com 2023-07-08T10:50:30.420415+00:00 ABlog https://blog.readthedocs.com/sphinx6-upgrade/ 2023-01-04T00:00:00+00:00 Benjamin Balder Bach <section id="sphinx-6-is-out-and-has-important-breaking-changes"> <div class="admonition note"> <p class="admonition-title">Note</p> <p><strong>Important updates to this post ⬇️</strong></p> <ul class="simple"> <li><p><a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/">sphinx-rtd-theme</a> 1.2.0 has been released with support for Sphinx 6.</p></li> <li><p><a class="reference external" href="https://github.com/readthedocs/readthedocs.org/pull/9654">A necessary platform update on Read the Docs</a>, released on February 7th 2023, allows for jQuery to be included in certain complex scenarios pertaining Sphinx 6.</p></li> <li><p>Sphinx 6.1 has also been released with frequent patch releases. Be aware of <a class="reference external" href="https://github.com/sphinx-doc/sphinx/issues">open issues on the Sphinx GitHub project</a>.</p></li> <li><p><a class="reference external" href="https://pypi.org/project/sphinxcontrib.jquery/">sphinxcontrib-jquery</a> 3.0.0 does not work on local builds while version 2.0.0 relies on Google’s CDN. <a class="reference external" href="https://github.com/sphinx-contrib/jquery/pull/14">A fix</a> is waiting for review and release.</p></li> </ul> </div> <p>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:</p> <ul class="simple"> <li><p>Python 3.8+ is required. To enable this on Read the Docs, you will need to specify a Python version using the <a class="reference external" href="https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python" title="(in Read the Docs user documentation v9.15.0)"><span>build.tools.python</span></a> setting. If it’s possible for your project, you can make the jump all the way to Python 3.11.</p></li> <li><p>Support is dropped for docutils 0.14, 0.15, 0.16 and 0.17. It now supports only docutils 0.18 or 0.19.</p></li> <li><p><a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/">sphinx-rtd-theme</a> will support Sphinx 6 from 1.2.0, including docutils 0.18. You can already install the release candidate: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">sphinx-rtd-theme==1.2.0rc4</span></code>.</p></li> <li><p>Bundled jQuery is removed. The JavaScript asset is easily added back using the new extension <a class="reference external" href="https://pypi.org/project/sphinxcontrib.jquery/">sphinxcontrib-jquery</a>. It is included automatically by <a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/">sphinx-rtd-theme</a>, so if you are using our theme, you will also continue to have jQuery available in your documentation.</p></li> <li><p>All bundled JavaScript was removed, including also underscore.js.</p></li> </ul> <p>For more information and full details you can read the <a class="reference external" href="https://www.sphinx-doc.org/en/master/changes.html#release-6-0-0-released-dec-29-2022">Sphinx changelog</a></p> <p>Since most documentation projects rely on themes and extensions, we recommend checking for Sphinx 6 support in those projects before upgrading.</p> <section id="less-maintenance-work-in-the-future"> <h2>Less maintenance work in the future</h2> <p>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.</p> <p>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.</p> </section> <section id="possible-issues"> <h2>Possible issues</h2> <ul class="simple"> <li><p>Sphinx 6.0 and 6.1 are very fresh releases. As such, please remember:</p> <ul> <li><p>Not all extensions and themes have added support for the new versions!</p></li> <li><p>You may experience issues if you have not pinned your documentation dependencies.</p></li> <li><p>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.</p></li> </ul> </li> <li><p>We are actively updating our theme to support Sphinx and docutils updates. If you find regressions in any new releases of the <a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/">sphinx-rtd-theme</a>, please don’t hesitate to <a class="reference external" href="https://github.com/readthedocs/sphinx_rtd_theme/">open an issue on GitHub</a>.</p></li> </ul> <p>If you suspect that upgrade issues are caused by dependency mismatches, we recommend taking the approach of <em>reproducible builds</em>. This includes explicitly specifying all relevant dependencies. Read more in our documentation’s <a class="reference external" href="https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html" title="(in Read the Docs user documentation v9.15.0)"><span class="xref std std-doc">introduction to Reproducible Builds</span></a>.</p> </section> <section id="don-t-fancy-upgrading"> <h2>Don’t fancy upgrading?</h2> <p>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.</p> <p>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.</p> <div class="system-message"> <p class="system-message-title">System Message: INFO/1 (<span class="docutils literal">/home/docs/checkouts/readthedocs.org/user_builds/test-githubblog/checkouts/latest/sphinx6-upgrade.rst</span>, line 93); <em><a href="#id1">backlink</a></em></p> <p>Duplicate explicit target name: “sphinx-rtd-theme”.</p> </div> </section> </section>

Important updates to this post ⬇️sphinx-rtd-theme 1.2.0 has been released with support for Sphinx 6.

2023-01-04T00:00:00+00:00