Sphinx 4.4 release and other ecosystem news¶
In this post we spread the word about the most relevant news of the Sphinx ecosystem of the past weeks, including Sphinx itself as well as extensions and themes developed by the community.
Sphinx 4.4 release¶
Sphinx 4.4 was released on January 17th with numerous changes, including:
- Better control of intersphinx references with the
One of the power features of Sphinx is the ability to include cross references across projects, using intersphinx. By default, Sphinx transparently attempts to locate objects in external projects if they are not found in the current one, which is useful but also can become confusing in some cases. The new
externalrole, coupled with the intersphinx_disabled_reftypes configuration introduced in Sphinx 4.3, enables documentation writers to control when intersphinx references should be used.
You can use the new
:external:role as follows:
External reference: :external:py:class:`zipfile.ZipFile`. External reference with constrained domain lookup: :external+python:py:class:`zipfile.ZipFile`.
See more information in
the official documentation.
sphinx.application.Sphinx.add_js_file()now accepts a new
loading_methodparameter that can either be
"defer", which results in the script being loaded with the async or defer HTML attributes respectively.
- Proper error messages when autosummary does not find a package
Sphinx ships the autosummary extension to automatically generate API pages of a Python library. However, autosummary used to raise misleading error messages if the target library failed to import, which resulted in user frustration. This problem has now been fixed and autosummary properly points out the reason of the
You can read the complete Sphinx 4.4.0 release notes online.
Using Sphinx 4.4 on Read the Docs¶
Sphinx 4.4 is supported on Read the Docs. By default, RTD will install the latest version for you,
as described in our documentation.
If you are pinning your dependencies
to improve the reproducibility of your builds,
you can change the pinned version to
in either your
Sphinx themes and extensions¶
Several other extensions and themes saw new releases recently, including:
- pydata-sphinx-theme 0.8
pydata-sphinx-theme is a Sphinx theme based on Bootstrap CSS developed by the PyData community, The Read the Docs team collaborated with the developers to make some of the new features of 0.8 behave correctly in our platform, in particular the custom version switcher. As Chris Holdgraf summarizes in this Twitter thread, the new version brings other interesting additions, like better depth control of the left sidebar and custom SVG icons.
- sphinx-codeautolink 0.9
sphinx-codeautolink is a Sphinx extension to automatically include links inside code blocks. The 0.9 version now links Python builtin objects if intersphinx is properly configured and has several logging improvements.
- sphinxcontrib-constdata 1.0
sphinxcontrib-constadata is a new Sphinx extension that allows documentation writers to easily load data stored in CSV, JSON, and YAML files. For example, it can be used to load UI labels (button labels, menu selection labels) from external files instead of hardcoding them in the documentation for better maintenance, for example:
Choose menu item :constdata:label:`menu.yaml?FileSaveAs`.
We are excited about seeing new and old Sphinx extensions being developed by the community, and we thank the Sphinx maintainers for their excellent work.
Considering using Read the Docs for your next Sphinx? Check out our documentation to get started!