Read the Docs Blog - Posts tagged release

Sphinx 4.4 release and other ecosystem news

2022-01-26T00:00:00Z

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

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 sphinx==4.4.0 in either your requirements.txt or environment.yml.

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.

Demo of sphinx-codeautolink

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.

Preview of MyST integrated in 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!

Theme release 1.0.0rc1

2021-08-23T00:00:00Z

Update: Version 1.0.0 has been released!

The 1.0.0 version of sphinx_rtd_theme was released Sept 13, 2021. You can install the latest version with:

$ pip install "sphinx-rtd-theme~=1.0.0"

Alternatively, you can upgrade the version installed using:

$ pip install --upgrade sphinx-rtd-theme

We are closing in on the next official release of sphinx_rtd_theme, and we’re happy to announce that release candidate version 1.0.0rc1 was released to PyPI last week! Project maintainers can contribute to the final release by testing the release candidate and raising any potential bugs on our issue tracker.

Version 1.0.0 adds support for Sphinx 4, fixes several issues stemming from docutils 0.17, and contains several backwards-incompatible changes.

Backwards incompatible changes

Users need to be aware of several backwards incompatible changes before upgrading:

Support dropped for old dependencies: Support is removed for Sphinx versions 1.6 or older, and for Python versions 3.0 to 3.3. Theme developers no longer test using these versions and compatibility is not guaranteed for these versions.
HTML4 support will be removed: Support for the Sphinx HTML4 writer will be deprecated in release 2.0. A deprecation warning was added to alert users still using the HTML4 writer.
Installation from source will be deprecated soon: Tentatively scheduled for release 3.0, installation from source will no longer be a supported installation method. Currently, users are installing directly from our GitHub repository, which complicates development of static assets. A deprecation warning was added to alert users of the upcoming change.

Highlights

Here are some of the most significant additions included in release 1.0.0:

Support for new dependencies: The theme now supports Sphinx 4 and docutils 0.17, both the latest in each respective release series.
New accessibility features: Also added were a number of accessibility updates, including better keyboard navigation support and more descriptive navigation for screen readers.
Added 4 new translations: The theme is close to being almost fully translated in 14 different languages. This will provide project maintainers with localized navigation elements and accessibility content.

The theme roadmap has more information on upcoming releases, and backwards incompatible changes for each. A full list of changes included in this release is available in the theme changelog.

Testing

The 1.0.0rc1 release is a pre-release package, meaning it will not install by default as the most recent release. Project maintainers will need to specify the release version explicitly to install the release candidate.

In your package’s extra_requirements, or a separate requirements.txt file, you can pin this dependency with:

sphinx_rtd_theme~=1.0.0rc1

If you notice any new, unwanted behavior, feel free to open an issue on our issue tracker.

Upcoming changes

We have several upcoming releases planned, covered in more depth in the theme roadmap.

Our next official release, currently targeted for October or November, will be version 1.1. This release will contain additional bug fixes and will be the last release supporting Sphinx versions less than 3.0. The next planed release will be version 2.0, in early 2022.

The 2.0 release will be dropping support for a number of old dependencies, including Sphinx versions < 3.0, Sphinx HTML4 writer support, and Internet Explorer 11.

As the theme moves away from supporting direct installation through our GitHub repository, we want to preserve development previews of theme releases. In addition to several more focused releases on the theme roadmap, we will also be periodically publishing development releases to PyPI. This will be the prescribed method to use unreleased theme changes.

Thanks!

Special thanks to contributor Blendify for keeping up with support for fresh dependencies, and new contributor nienn for helping with bug fixes and the heavy amount of testing required for this release!

Release for May 12, 2017

2017-05-12T00:00:00Z

Yesterday, we rolled out improved webhook management for projects, and several bug fixes around our upgrade to Sphinx 1.5.

Webhook management

We’ve been slowly making upgrades to our webhook management page. Projects that set up new webhooks will see a list of webhooks that we have configured, including HTTP exchanges that we encounter from each remote webhook.

Some of the other improvements to our webhook management include a new generic webhook endpoint, the ability to create arbitrary webhooks, and the ability to now re-establish webhooks on a per-provider basis.

You can play with the new features by selecting a project, opening the project admin dashboard, and selecting Integrations. If your project is relatively new, webhook integrations will be created for existing remote webhooks. If your project has been configured for a long time, or you are using our old webhook endpoints, such as http://readthedocs.org/github, you won’t notice anything new on the integrations dashboard page. You can still manually create a webhook and configure your repository to point to the new Read the Docs webhook endpoint however.

Bug fixes

Following the release of Sphinx 1.5, we set this version as the default version for Sphinx projects on Read the Docs. This in turn caused an issue with our override of the Sphinx search mechanism. We currently override this to provide our own search indexes, however the patch to this file was incompatible with Sphinx 1.5.

Due to this incompatibility, if a search query did not return anything from our indexes, but did match the Sphinx internal index, the links would have been incorrect.

We are now patching this search mechanism regardless of which version of Sphinx is used, and the broken links are no longer returned in the search results.

Problems?

If you encounter any problems with any of the recent changes, feel free to open up a bug report on our issue tracker.