Sphinx 4.4 release¶

Sphinx 4.4 was released on January 17th with numerous changes, including:

Better control of intersphinx references with the :external: role

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 external role, 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.

New asynchronous methods to load JavaScript files

The method sphinx.application.Sphinx.add_js_file() now accepts a new loading_method parameter that can either be "async" or "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 ImportError.

You can read the complete Sphinx 4.4.0 release notes online.

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`.

Upcoming¶

The Executable Books Project team is working on several exciting things around MyST, including the upcoming MyST-Parser 0.17 release and direct integration with Jupyter notebooks.

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!