Read the Docs Blog - Posted in 2021

Sphinx and Markdown around the world in 2021

2021-12-20T00:00:00Z

Read the Docs has been committed to improving the accessibility and user experience of Sphinx since the start, and that includes the markup language in which the documentation is written. Years ago, after carefully listening to users, we announced recommonmark to help bridging the immense popularity of Markdown with the powerful capabilities of Sphinx. (It is now deprecated in favor of MyST - keep reading to know more.)

It is no surprise that Markdown is in such demand: thanks in large part to the huge popularity of GitHub, Markdown is nowadays the most widely used markup language in open-source projects, ahead of reStructuredText, the second in the list, by an order of magnitude.

This year, thanks to the CZI Grant we received last year and the effort of other communities, especially the Executable Book Project, we have devoted lots of resources to help consolidate Markdown as a compelling markup language for Sphinx.

Writing Markdown in Sphinx

To that end, we recognized the potential of MyST as a successor of recommonmark, and deprecated the latter in favor of MyST-Parser. To start writing Markdown in Sphinx, you need to follow three steps:

Install MyST-Parser: pip install myst-parser
Add myst_parser to the list of Sphinx extensions:

extensions = [
    # ...other extensions
    "myst_parser",
]

Start writing content in *.md files!

You can find more information in the MyST-Parser documentation.

Talks and workshops at conferences

Luckily the migration to MyST-Parser was trivial for most projects, but we still wanted to spread the word about the best practices for creating Sphinx projects on Read the Docs using MyST Markdown. We set the goal of presenting at every large scientific Python event out there, and all our proposals were accepted [1]! Throughout 2021, we were present in several events:

We conducted a networking session and a sprint about documentation at SciPy US, and in that event we were kindly invited to the sktime documentation sprint.
We delivered a 90 minutes tutorial called “Document your scientific project with Markdown, Sphinx, and Read the Docs” at PyData Global, and we repeated a 120 minute version in Spanish language at the SciPy Latin America.
And we also gave shorter talks at more broadly focused events: PyCon Latam and PyCon Spain.

We have generated workshop material that everybody is welcome to use:

A main repository containing some introductory slides about Sphinx, and detailed notes of every step of the tutorial.
A supporting repository with a tiny Python library that gets used during the tutorial, inspired by the one used in the official Sphinx tutorial we authored with the help of the Sphinx community.

And finally, we have also developed an interactive web application to translate small bits of reStructuredText to MyST Markdown.

[1]	We also have submitted a proposal for SciPy India, which was postponed to January 2022. EuroSciPy and SciPy Japan didn’t happen in 2021.

Future plans

We are excited to see that the Executable Books team has released myst-docutils, which should help docutils parse CommonMark directly and possibly pave the way for Sphinx to parse Markdown without the need of third party extensions. Hopefully that will also make it easier for Sphinx to showcase Markdown content in its documentation more prominently, and users will be able to naturally pick the markup language that best suits their needs, be it reST or MyST.

—

Considering using Read the Docs for your next Sphinx, Jupyter Book, or MkDocs project? Check out our documentation to get started!

Read the Docs newsletter - December 2021

2021-12-14T00:00:00Z

Welcome to the latest edition of our monthly newsletter, where we share the most relevant updates around Read the Docs, offer a summary of new features we shipped during the previous month, and share what we’ll be focusing on in the near future.

Company highlights

We successfully deployed mitigation measures against spam, and we are happy to report that the amount of abusive projects has dramatically decreased.
We started tracking usage of different parts of our application in a more systematic fashion which will enable us to make better product design decisions going forward.

New features

We revamped our support for webhooks: now they have a dedicated section in the project settings, you can customize the payload, and you can inspect the status of each webhook delivery. Interested in receiving build notifications on Slack or Discord? Now you can!

Revamped webhooks

On Read the Docs for Business, we improved our security audit logs to show information from all the organization according to its plan.

Organization audit logs

We expanded our documentation to describe how document projects with Jupyter Book and how to use Poetry for dependency management.

Thanks to our external contributor Rok Roškar.

You can always see the latest changes to our platforms in our Read the Docs Changelog.

Upcoming features

With the Christmas holidays coming up, we will have a few slow weeks ahead.

Ana will keep working on the complete redesign of our community site, which is already making good progress.
Anthony will work with Ana on the structure of our new community site and document our upcoming new user interface.
Eric will continue working on our commercial SSL provisioning and CDN with Santos.
Juan Luis will continue promoting our Embed API as well as wrap up his work on the Sphinx tutorial.
Manuel will adjust the new logging and spam fighting systems, and continue making progress on the new metrics infrastructure.
Santos will do the final bits of CDN work on our commercial site, finish moving our development documentation to a separate project, and continue unifying our commercial and community codebases.

Possible issues

Last week we accidentally banned a small number of legitimate users and they saw their projects temporarily blocked. As soon as we noticed this we apologized to the affected users and rolled back the ban, and the documentation is now serving normally.

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Announcing Embed API v3 and sphinx-hoverxref 1.0

2021-12-07T00:00:00Z

We are thrilled to announce the availability of Read the Docs Embed API v3, along with its official client, sphinx-hoverxref 1.0. This work has been possible in part thanks to the the CZI grant we received.

The value of content embedding

As we wrote in our first blog post about sphinx-hoverxref, one of the most powerful features of Sphinx is the possibility of creating cross references to other documentation projects. However, a reader finding several links in a technical documentation might need to open several browser tabs to fully understand the context, resulting in a lot of friction in the form of context switching.

One way of mitigating the problem is to show a small preview in the form of tooltip or modal with the contents of the link. This is where the Embed API and sphinx-hoverxref come in.

sphinx-hoverxref is a Sphinx extension that addresses this problem by adding tooltips on the cross references of the HTML documentation with the content of the linked section. To do so, it inserts a small JavaScript file that calls the Read the Docs Embed API when the user hovers any link. Back in June we announced intersphinx support in sphinx-hoverxref 0.6b1, which allowed users to include modals and tooltips also for cross references to other projects.

sphinx-hoverxref displaying a tooltip including an equation

Some big projects already using it include Tweepy, a Python client for Twitter, and Scrapy, a framework for crawling websites.

Embed API v3 and sphinx-hoverxref 1.0

After some months of work, we are excited to publish v3 of our Embed API, and with it, version 1.0 of sphinx-hoverxref.

Among other things, the new versions allow you to embed content from pages hosted outside Read the Docs. For security reasons, we have an allowlist of such external domains that currently includes Python, NumPy, SciPy, SymPy, and we would like to invite the community to suggest more domains to add.

Other additions and fixes include:

Support for JS and CSS assets in Sphinx 4.1+.
Support for glossary / term and sphinxcontrib-bibtex.
Avoid showing the browser built-in tooltip for links that have the extension enabled.

Finally, version 3 of the Embed API paves the way for supporting non-Sphinx projects in the future.

Embedding content with sphinx-hoverxref

To use sphinx-hoverxref in your Read the Docs project, declare it as part of your dependencies:

requirements.txt

sphinx==4.3.1
sphinx_rtd_theme==1.0.0
sphinx-hoverxref==1.0.0

And add it to your list of Sphinx extensions:

conf.py

extensions = [
    # ...other extensions
    "hoverxref.extension",
]

To enable the extension on all :ref: of your documentation, set the hoverxref_auto_ref to True:

conf.py

hoverxref_auto_ref = True

And you will start seeing tooltips on your internal references. Apart from :ref: roles, you can also enable tooltips on:

Note

sphinx-hoverxref includes the JavaScript embed client in the HTML assets, but it is not yet available as a standalone library that can be reused with standard frontend packaging tools. If you would like to see this happening, let us know.

Calling the Embed API directly

As explained in our embedding guide, you can call the API directly from any HTTP client:

$ curl -s "https://readthedocs.org/api/v3/embed/\
> ?url=https://docs.readthedocs.io/en/latest/features.html\
> %23read-the-docs-features" | python -m json.tool
{
  "url": "https://docs.readthedocs.io/en/latest/features.html#read-the-docs-features",
  "fragment": "read-the-docs-features",
  "content": "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs ...",
  "external": false
}

Or visually explore the query in the web interface instead.

The reference documentation includes more detail about the parameters and return values of the API.

Try it out!

We would like to invite the community to try out these features and send us feedback. With the help of our users, we will keep moving towards a more cohesive documentation ecosystem of interlinked Python projects.

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Read the Docs ❤️ Jupyter Book

2021-11-11T00:00:00Z

We are proud to announce that now Jupyter Book projects are supported on Read the Docs!

Both Read the Docs and The Executable Book Project, the folks behind Jupyter Book, share a common passion for documentation, and we have been collaborating on various topics for some time already. For example, we started promoting MyST in favor of our recommonmark back in April this year, and we wrote a guide on using Jupyter notebook with Sphinx that benefitted a lot from their feedback.

Now we are happy to announce that Jupyter Book itself is supported on Read the Docs, after some thorough discussion about the possible implementations and thanks in large part to the Jupyter Book developers, who addressed all the minor incompatibilities that prevented this from happening.

What is Jupyter Book?

According to its own documentation,

Jupyter Book is an open source project for building beautiful, publication-quality books and documents from computational material.

Jupyter Book is the flagship product of the Executable Book Project, an international collaboration between several universities and software projects seeking to build open source tools that facilitate publishing computational narratives using the Jupyter ecosystem.

Even though Jupyter Book is much younger than Read the Docs as a project, it has become very popular in recent times among scientific software developers and educators. It enables users to write publication-quality content in Markdown thanks to MyST (a Markdown dialect compatible with Sphinx we started promoting back in April this year), use Jupyter notebooks to author content thanks to MyST-NB (featured in our Jupyter on Sphinx guide), easily add interactivity thanks to Thebe, and much more.

Why a change was needed

Read the Docs supports two documentation generation systems Sphinx and MkDocs. Adding extra systems is difficult with the current codebase, because it requires lots of effort to match all the features currently supported by the existing ones.

On the other hand, even though Jupyter Book leverages Sphinx “for almost everything that it does”, it purposefully hides some of the Sphinx implementation details from the user to create a more user friendly experience. One of the consequences of this is that the assumptions that Read the Docs makes to build the documentation of Sphinx projects don’t hold: in particular, Jupyter Book uses a declarative configuration file _config.yml that gets translated on the fly to the Sphinx dynamic configuration usually stored in conf.py. As a result, Jupyter Book projects could not be hosted on Read the Docs - until now!

How to deploy a Jupyter Book project to Read the Docs

With the current development version of Jupyter Book, you can now export a Sphinx conf.py configuration from the Jupyter Book declarative _config.yml and save it to disk, which allows Read the Docs to build the documentation from it like any other Sphinx project.

The challenge then becomes keeping both configuration files synchronized, since every update to _config.yml or new Jupyter Book release can potentially produce changes in the conf.py. As described in the official documentation, users can either manually export the configuration running a command at will, or set up an automation to do it on every change.

To see this in action, have a look at this example project that contains the bare minimum to make the demo book work on Read the Docs.

We are excited that this is now possible and look forward to seeing more projects built with Jupyter Book!

—

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Read the Docs newsletter - November 2021

2021-11-04T00:00:00Z

Company highlights

During the first week of November we attended the 2021 Essential Open Source Software for Science Annual Meeting, an event organized by the CZI Science team. We are thrilled to connect with projects in the Open Science ecosystem.
We upgraded our systems to Python 3.8 and Ubuntu 20.04 LTS. This will allow us to leverage newer Python features and use more up to date dependencies.
The Read the Docs tutorial we started writing as part of the CZI grant we received is now complete! We plan to keep updating it with user feedback and keep improving other parts of our documentation.

New features

We added a checkbox to subscribe to our newsletter on new signups. If you haven’t already, you can also subscribe using the form on the top right of our blog.
We no longer show the rebuild option on closed or merged pull request builds.
We now re-sync VCS accounts for SSO organization daily.

Thanks to our external contributors Adam Dangoor, Arthur Milchior, Carlton Gibson, Deepto, Jürgen Gmach, and Maksudul Haque.

You can always see the latest changes to our platforms in our Read the Docs Changelog.

Upcoming features

Ana will be working on bringing the mockups of our new landing pages to reality.
Anthony will keep working on finances and taxes, and helping Ana with the frontend work.
Eric will send out a report for our grant work, and work with Santos on implementing CloudFlare for our corporate site.
Juan Luis will work on moving our development documentation to a separate project, finish the Sphinx tutorial, spread the word about MyST Markdown, and promote our Embed API.
Manuel will add mechanisms to fight spam in our platform and improve our internal metrics.
Santos will wrap up the custom outgoing webhooks and keep unifying the code of our community and commercial sites.

Possible issues

The docutils 0.18 release from late October is incompatible with older versions of Sphinx, which are still used by a significant number of projects on Read the Docs. A large number of them were not pinning their dependencies and have experienced broken builds, which has resulted in a large number of issues and support requests. We have written a blog post explaining the situation and the ways to solve it.

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Build errors with docutils 0.18

2021-11-02T00:00:00Z

Starting about a week ago, some users started reporting new errors with their project builds. In most cases, these errors appeared out of nowhere and are usually rather cryptic errors referencing Sphinx and docutils.

So, what is happening?

These errors are due to an incompatibility bewteen old versions of Sphinx and one of its dependencies, docutils. You probably have not directly interacted with docutils, but this is the library that provides reStructuredText parsing to both Sphinx and to the Python standard library documentation tooling.

There are a number of errors that users have reported due to this incompatibility, but the most common error is:

TypeError: 'generator' object is not subscriptable

If your project’s builds suddenly start failing with the above error message, or other cryptic errors that don’t seem related to your project, your project is most likely encountering this bug.

Why is this happening?

The underlying cause for this error is using an outdated version of Sphinx (version < 3.0) with the latest release of docutils (version 0.18, released October 26). This latest release of docutils is no longer comptible with Sphinx versions 1.x and 2.x, however these versions do not specify a upper limit to the version of docutils installed, and so will install the latest release by default.

The reason so many projects use an old version of Sphinx is that, before October 2020, Read the Docs had a more strict pinning policy and Sphinx 1.8 was the default version. New projects are not affected.

Fixing the error

We have proposed to the Sphinx and docutils maintainers a solution that doesn’t involve manual intervention. However, for now we suggest you manually resolve this issue for any of your projects that have encountered the bug.

There are two ways to resolve this issue:

Upgrade Sphinx to version 3 or later

We recommend this option for most users. If your project doesn’t specifically still require Sphinx 1.x or 2.x, your project can most likely be upgraded, without issues, to a modern version of Sphinx. As a bonus, you’ll be able to use the latest Sphinx releases and extensions that only support modern Sphinx releases.

It is worth noting that one reason why you might still be using an old version of Sphinx is if you generate API documentation for Python 2 compatible code. In this case, you’ll have more work ahead of you in order to upgrade, as Sphinx version 3 and 4 only support Python 3.

Downgrade docutils

This is the next best option if you can’t immediately upgrade Sphinx. If you are familiar with Python packaging, the best specifier to use is docutils<0.18.

Fixing the error on Read the Docs

If you aren’t already, you should add a configuration file for your project, so that you can specify additional dependencies to install at build time. There are a few supported methods for installation, depending on how you normally install dependencies for your project. If you are not currently specifying any dependencies on Read the Docs, you most likely will want to use the python.install.requirements configuration option.

This is how the reference .readthedocs.yaml and docs/requirements.txt files would look like:

.readthedocs.yaml

version: 2

python:
  install:
  - requirements: docs/requirements.txt

docs/requirements.txt

docutils<0.18

If you still experience problems, feel free to open an issue.

Ubuntu 20.04, Python 3.10, and support for Node, Rust, and Go

2021-10-14T00:00:00Z

We are excited to announce that now Read the Docs users can use a newer build specification in their projects that will change the base image to one based on Ubuntu 20.04, ship the recently released Python 3.10, and allow users to easily specify the version of Node.js, Rust, and Go. This feature has been a long time in the making, and we think it will simplify the configuration of many projects.

Previous situation

The Docker images used by our builders were based on Ubuntu 18.04. Recently, we added a new feature to install custom system packages, which allowed many projects to have better control of their build process without having to use conda to manage non-Python dependencies.

However, this Ubuntu version was released three years ago and, even though it was good enough for most projects, we have been receiving requests to upgrade certain system packages over the years. Since these are managed through the operating system package manager, and we do not provide a way to add custom Personal Package Archives, such upgrades were not possible.

Many Python projects use a secondary programming language for a variety of reasons. Established compiled languages like C, C++, and FORTRAN have readily available compilers that will work for the majority of use cases. However, other younger technologies move at a faster pace, and developers often want specific versions of the toolchains that cannot be installed with the system package manager. This affected projects that combine backend and frontend code that need Node.js to compile their JavaScript sources, such as Jupyter extensions, and libraries with performance-critical code written in Rust or Go.

We have often suggested specifying custom versions of non-Python dependencies using conda, to specify custom versions of non-Python dependencies, but this requires learning another tool that might be unfamiliar for some projects.

New `build` YAML configuration

To overcome all these problems, we have added a new configuration value, build.tools, that receive a dictionary of toolchain versions. This new configuration requires specifying the base image name in build.os, currently ubuntu-20.04. Our configuration documentation contains a simple example:

version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-20.04
  tools:
    python: "3.9"
    # You can also specify other tool versions:
    # nodejs: "16"
    # rust: "1.55"
    # golang: "1.17"

And you can draw inspiration from some community projects that are using this feature already:

cryptography, the reference Python library for cryptographic algorithms, can now specify the Rust version required to build the package.
parsel, a Python library to manipulate HTML and XML using XPath and CSS selectors, leverages the new specification to build their documentation on the just released Python 3.10.
Thebe, a Jupyter-powered tool to make HTML pages interactive, needs Node.js to build the latest version of the code.

Do you think this feature will be useful for you as well? Give it a try and let us know.

Remember you can always see the latest changes to our platforms in our Read the Docs Changelog.

—

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Read the Docs newsletter - October 2021

2021-10-07T00:00:00Z

Company highlights

We have resumed sending our blog updates by email. You can subscribe to our newsletter so you don’t miss them.
Version 3 of our Embed API is now implemented, thanks to the CZI grant we received. We will give more details about it soon.
We have reworked our team page to give you a better idea of who we are and how we work at the company.

New features

You can now use our newer build specification that leverages a newer image based on Ubuntu 20.04 and gives more control over the versions of Python, Node.js, Rust, and Go. Projects like pypa/cryptography and thebe are already using it, and we will make an announcement with more information soon.
We have added a new section to our Dashboard that exposes user security logs.

Security logs

We have added a button on the Analytics section to download all your data, so you are not limited by the last 30 days that we show.
We have revamped our onboarding process. If you are new to Read the Docs, you can now fork our template repository and follow our tutorial to learn how to use the platform. We plan to keep expanding the tutorial during the coming weeks.
We have made our how-to guides more visible and simplified its categorization, in addition to other documentation improvements.

Thanks to our external contributors Mozi and Dmitry.

You can always see the latest changes to our platforms in our Read the Docs Changelog.

Upcoming features

Ana will work on the UI of our landing and marketing pages, while making progress with version 1.1 of our Sphinx theme.
Anthony will resume work on our new product interface and wrap up some financial updates.
Eric will focus on expanding our CDN functionality on the commercial site, as well as addressing some upcoming changes to how custom domains work on Read the Docs Community.
Juan Luis will document several recent changes, such us the new build specification and our support for generic webhooks, and continue expanding our tutorial and improving the SEO of our docs.
Manuel will finish the migration of our services to Ubuntu 20.04, release a new version of sphinx-hoverxref that uses our new embed API, and gather feedback on our new build specification.
Santos will continue consolidating our Community and Commercial codebases, finish the work on generic webbooks for easier integration with Slack and other tools, enable Commercial users to create new subscriptions after they cancel, and collaborate with Eric on the CDN issues.

Possible issues

We are detecting an increasing number of spammy projects on our platform. While this rarely affects legitimate users, it is still a concern to us and we are planning to take measures to tackle it.

In addition, some projects experienced networking issues due to the expiration of Let’s Encrypt root certificate. We deployed a fix shortly after the problem was reported.

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Read the Docs newsletter - September 2021

2021-09-02T00:00:00Z

Company highlights

We have published the first release candidate of version 1.0.0 of our Sphinx theme, which adds support for recent versions of Sphinx and docutils among other things, and announced our future plans for it. Check out the linked blog post to know more. Update: We have released 1.0 to PyPI
The first part of the new Read the Docs tutorial, which we wrote as part of our CZI grant, is online! We hope that it serves as a better starting point for people seeking to learn how to use our platform.

New features

Commercial users can now share specific versions of their projects and log out from the flyout menu.
We added the possibility for users to remove themselves from a project without having to ask an owner to remove them (as long as they are not the only owner of the project).
We fixed a small usability issue with our search-as-you-type box, that ignored the first typed characters under certain circumstances.
We have documented our unofficial support for Gitea, and made other minor documentation fixes.

Thanks to our external contributors Mozi, Maksudul Haque, Stefano Costa, and Christian Clauss.

You can always see the latest changes to our platforms in our Read the Docs Changelog.

Upcoming features

Ana will continue researching tools for conducting automated testing on our Sphinx theme, review pull requests corresponding to the 1.1 milestone, and make some small styling improvements to our documentation.
Anthony will work with Ana on testing our Sphinx theme, in addition to resuming work on our new user interface and doing some financial updates.
Eric will keep pushing updates on our Commercial landing page and continue working on our sales processes. He’s also working to continue building EthicalAds as well.
Juan Luis will continue working on our Read the Docs tutorial, improving our onboarding experience, and put our email marketing and on-site notifications to work.
Manuel will finish the work on our new Docker images and build process, and keep designing our upcoming GitHub Application.
Santos will implement a new Slack integration, work with Manuel on the GitHub Application, and build a user interface for audit tracking.

Possible issues

We have been making changes to how we store cookies to make our site more secure. This has caused some minor issues in certain web browsers or to users that were embedding private documentation pages inside an iframe.

Considering using Read the Docs for your next Sphinx or MkDocs project? 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!

Read the Docs Blog - Posted in 2021

Sphinx and Markdown around the world in 2021

Writing Markdown in Sphinx

Talks and workshops at conferences

Future plans

Read the Docs newsletter - December 2021

Company highlights

New features

Upcoming features

Possible issues

Announcing Embed API v3 and sphinx-hoverxref 1.0

The value of content embedding

Embed API v3 and sphinx-hoverxref 1.0

Embedding content with sphinx-hoverxref

Calling the Embed API directly

Try it out!

Read the Docs ❤️ Jupyter Book

What is Jupyter Book?

Why a change was needed

How to deploy a Jupyter Book project to Read the Docs

Read the Docs newsletter - November 2021

Company highlights

New features

Upcoming features

Possible issues

Build errors with docutils 0.18

Why is this happening?

Fixing the error

Fixing the error on Read the Docs

Ubuntu 20.04, Python 3.10, and support for Node, Rust, and Go

Previous situation

New build YAML configuration

Read the Docs newsletter - October 2021

Company highlights

New features

Upcoming features

Possible issues

Read the Docs newsletter - September 2021

Company highlights

New features

Upcoming features

Possible issues

Theme release 1.0.0rc1

Backwards incompatible changes

Highlights

Testing

Upcoming changes

Thanks!

New `build` YAML configuration