Read the Docs Blog - Posted in 2022

Read the Docs newsletter - March 2022

2022-03-10T00:00:00Z

War in Ukraine and what it means for Read the Docs

2022-03-07T00:00:00Z

With news surrounding the invasion of Ukraine evolving rapidly, we felt it was necessary to provide an update to our users and customers.

At Read the Docs, we are outraged and saddened by the invasion of Ukraine and we condemn this act of violence as wrong and unlawful. We are monitoring the situation in Europe and how it relates to our employees, customers, and our services to the open source world.

Read the Docs is a very small company, with only seven employees, and fortunately none of them are currently in harm’s way. Our impact on the open source ecosystem, however, is bigger than our size, and we have users all over the world, including in Ukraine and Russia.

Impact on our services

We are continuing to monitor news that could potentially affect our users, including sanctions applied to the region.

Read the Docs is currently partially blocked in Russia by the Russian government. While we are working to resolve this, it does not appear that this block is related to war in Ukraine.

Other than this government block and potential effects from financial sanctions, our services are not impacted. Read the Docs is hosted and incorporated in the United States, and so any further changes to US sanctions would apply to our services.

What we are doing and what you can do

As the situation develops, we will be transparent about any actions we take. We take our role of helping the open source community with documentation seriously and we aim to be a platform for all developers.

Over the coming days, our advertising arm EthicalAds will be running a series of community ads aimed at raising money for the United Nations Crisis Relief Fund and other missions aimed at humanitarian aid for Ukraine. If you can donate to help provide humanitarian aid, please do.

We are hoping that peace is restored as quickly as possible.

Deprecation of the git:// protocol on GitHub

2022-03-01T00:00:00Z

Last year, GitHub announced the deprecation of the unsecured Git protocol due to security reasons. This change will be made permanent on March 15, 2022.

At Read the Docs we found around 900 projects using a Git protocol URL (git://github.com/user/project) to clone their projects. To save time for our users, we have migrated those to use the HTTPS cloning URL instead (https://github.com/user/project).

But there are other places where projects may be using a Git protocol URL, like in submodules or dependencies. You’ll need to migrate those to use a supported protocol in order for your builds to keep working after March 15, 2022. In most cases, this means changing URLs that start with git:// to start with https:// instead. If you have doubts, please check the documentation of the tools you are using, for example:

Note that this applies only to repositories hosted on GitHub, repositories using providers that support the Git protocol won’t be affected.

Read the Docs tries to keep users informed about deprecations and breaking changes that may impact projects. To receive future updates like this, subscribe to our newsletter.

Read the Docs newsletter - February 2022

2022-02-08T00: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 updates

We have mostly finished migrating Read the Docs for Business users to Cloudflare for SSL. There are lots of interesting features this will enable, so stay tuned for updates there.
We’re sad to announce that Juan Luis has moved on from Read the Docs as our developer advocate. The work he did was vital towards getting our CZI grant mostly finished, and we thank him for his time spent bettering the RTD, Sphinx, and docs community.
On a related note, we’re going to be hiring again soon to fill another position. It will be a bit different and likely a product-focused Python development position. If you’re interested, please let us know.

New features

In January we continued to work on refactors and internal changes. Among the major user-facing changes:

We fixed a bug in Bitbucket that didn’t allow us to properly sync user permissions. This resulted in a few support requests, but has now been resolved.
We improved our ability to mark projects as non-spam, so that we can validate a project isn’t spam and then make sure it doesn’t get flagged by our automated system.

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

Upcoming features

Cancelling a build is a long requested feature, and we’re getting close to implementing it.
We’re looking at tracking 404 pages in our project analytics, so that projects can easily fix up missing or outdated page links.
We are hoping to launch our revamped landing pages this month, which will give our front page a much needed refresh.
We are working to define a policy for canonical docs and cloned versions, so that we can more easily remove outdated docs for projects.
We’re working to investigate supporting a CDN on Read the Docs for Business, which will be an exciting new feature for our users there.
We’re looking at how to support multiple readthedocs.yml files in a single git repo.

Possible issues

We continue to see a good pace of development on the Sphinx project, with them adding support for docutils 0.18, and removing jQuery in a major refactor of their Javascript. We’re working to ensure that our theme and other parts of the ecosystem don’t break with these changes, and trying to be procative to address any possible issues. That said, there will likely still be some issues that sneak through with the release of Sphinx 4.5 (docutils upgrade) and Sphinx 5.0 (JS refactor).

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

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!

Read the Docs newsletter - January 2022

2022-01-12T00:00:00Z

Company highlights

We are now managing custom domains for our corporate users using Cloudflare SSL for SaaS, which will remove the manual work that was needed on our side and make the process of setting up a custom domain almost instantaneous. It also will allow us to offer a CDN much easier in the future.
We improved our spam classification system, and started blocking the dashboard on spammy projects. We are happy to report that the traffic to spammy projects has already reduced significantly.

New features

December and January have been slow months, and we mainly worked on internal changes and documentation improvements. Among the major user-facing changes:

We changed the Google Analytics from a persistent 30 day cookie to a session cookie that is deleted when the browser is closed. This will result in less data collected from users.
We split the developer documentation from the user documentation to avoid confusion and made our Read the Docs for Business docs more visible.
We expanded our user documentation with more examples on how to use MyST Markdown and a guide to migrate from reST to MyST (more about our committment to support MyST in our blog).

Thanks to our external contributor Çağatay Yiğit Şahin.

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

Upcoming features

Ana will continue working on the new landing pages, polishing the copywriting along with Juan Luis and translating the mockups to Pelican templates.
Anthony will continue working on frontend scaffolding and finance bits.
Eric will continue to focus on business and sales efforts, and performing code review.
Juan Luis will work with Ana in the new landing pages, and with Manuel in a new process to migrate users from legacy or deprecated configurations.
Manuel will wrap up the migration to Django 3, improve the queryability of the project configuration in our database, and refactor our task queue to improve its robustness.
Santos will add support for multiple .readthedocs.yaml files per repository.

Possible issues

The Python packaging ecosystem is evolving rapidly to accomodate for modern standards that will make our life easier, and in particular setuptools has been introducing some breaking changes in recent times. We anticipated this sort of breakage for our users so we pinned the setuptools version in late November. However, a small number of projects did not have this version cap active because of a bug on our side and experienced failing builds after a new setuptools release. We quickly fixed the problem and offered a range of possible solutions to affected projects.

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