Posts by Anthony Johnson

Read the Docs newsletter - September 2023

🚀 We started testing a new flyout menu as part of our beta test for documentation addons. The beta test is currently limited to projects using the build.commands configuration key.

🛣️ We continue to have a number deprecations in progress. We announced this month deprecations of installing using system packages, the configuration key build.image, and installation of pinned versions of Sphinx and MkDocs. Keep an eye on your email for any deprecation notifications, as we will continue to notify maintainers of projects that might be impacted.

Read more ...


Build errors with docutils 0.18

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?

Read more ...


Theme release 1.0.0rc1

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

Alternatively, you can upgrade the version installed using:

Read more ...


Defaulting New Projects to Python 3

New projects that are just getting started with Read the Docs will now use Python 3 by default. While it is still possible to configure your project to use Python 2.7 with our configuration file, we think it’s important to help push the Python ecosystem towards adopting Python 3.

Our default Python version is currently Python 3.7. Projects can also select Python versions 3.6 and 3.5 using our default build image. We will eventually remove support for building projects with Python versions 3.3 and 3.4, however it is still possible to select a build image with support for either version.

Read more ...


Incoming Webhook Deprecations

In the coming weeks and months, Read the Docs will be moving some projects away from our legacy incoming webhooks, towards our per-project webhook integrations.

Our legacy incoming webhooks were our first attempt at allowing providers like GitHub to automatically trigger builds on for projects on Read the Docs. These webhooks lacked a number of security features, and so, about two years ago, we replaced these with per-project webhook integrations instead. We added a number of features to per-project webhook integrations at the time, and we stopped new projects from using the old incoming webhooks.

Read more ...


Python 3.6 Support

A long time back, we wrote about started testing a new build image that uses pyenv to support multiple versions of Python. Until recently, we were selectively opting projects in to help test the new image, but at the beginning of the year, we added a configuration option to allow projects to opt in to using the new image before we make it the default build image.

In the near future, this build image will be the default build image, but for now, you can manually opt your project in using our YAML configuration file.

Read more ...


PyCon 2017 in Review

Things are finally getting back to normal for us after another very busy PyCon. It’s always wonderful seeing old friends and getting a chance to meet new friends from the community. PyCon provides a great outlet to talk to others in our community about the problems we all face as open source developers and open source companies – like funding, sustainability, and building community. We are sad to see PyCon leave Portland, but luckily PyCascades will soon be filling the void left in Cascadia after PyCon moves on.

This year, we announced official sprints on Read the Docs during the sprint week following PyCon. We focused our sprint efforts on code cleanup, in order to avoid the problems on-boarding new contributors we normally face as a large project.

Read more ...


Release for May 12, 2017

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

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.

Read more ...


Build Image Upgrades

Starting this week, we’ll be deploying a new default image for our documentation build environments. This image will change the default Python versions that are supported.

We aren’t expecting any issues to arise from this change, but be sure to raise any issues on our issue tracker if you notice any strange behavior. The new build image supports Python 2.7 and Python 3.5, dropping support for Python 3.4. If you require access to Python 3.4, we suggest you sign up for access to our next beta image.

Read more ...


Securing Subdomains

Starting today, Read the Docs will start hosting projects from subdomains on the domain readthedocs.io, instead of on readthedocs.org. This change addresses some security concerns around site cookies while hosting user generated data on the same domain as our dashboard.

Changes to provide security against broader threats have been in place for a while, however there are still a few scenarios that can only be addressed by migrating to a separate domain.

Read more ...


Read the Docs Awarded Mozilla Open Source Support Grant

Several months back, Mozilla launched a new initiative – the MOSS program – to provide financial support to the open source software projects it relies on. Mozilla allocated $1 million to the MOSS fund to provide grants for up to 10 projects matching the program’s criteria.

Read the Docs is among the first round of awards made for the MOSS program. Our proposed grant, for $48,000, is to build a separate instance that integrates with the Python Package Index’s upcoming website, Warehouse. This integration will provide automatic API reference documentation upon package release, with authentication tied to PyPI and simple configuration inside the distribution. API reference documentation on every release will be the starting point of this work, prose documentation generation will be more difficult here, as not all packages use Sphinx or rST for documentation.

Read more ...


Securing Build Processes

We’ve recently introduced a new build container subsystem based on Docker to readthedocs.org, which should go mostly unnoticed for users. We’re still ironing out some bugs with the system, so raise an issue on our issue tracker if you are noticing any new issues with your project builds.

This new system is part of an over-due security update to help isolate arbitrary code execution. As Read the Docs has grown, protecting against arbitrary execution was a rapidly growing concern. This build isolation layer was developed as part of readthedocs.com, where security concerns are paramount due to private repository access. We’ve been testing it for roll out on the community site since then, but hadn’t committed to switching production build servers over due to the number of possible side effects.

Read more ...


State of the Docs

August has historical significance for Read the Docs, so it seemed fitting to wrap up August by taking a moment to step back and reflect on what we’ve done in the last year.

What makes August so significant for us?

Read more ...


Report - July 2015

August was a hectic month for us. So busy, in fact, we never wrote this update. We dropped the ball on getting this report out on time, but hope to keep on top of future updates.

July was a month of stability fixes, with some substantial changes to our infrastructure. First, here’s an update on some of the goals we had set with our last monthly update:

Read more ...


Report - August 2015

August was a busy month for us. Write the Docs Europe was at the end of the month, and our focus has been on getting readthedocs.com into a public beta state. We’re nearing the end of the 3 month period that we budgeted for as part of our fundraiser and have a few more tasks to push out.

First, an update of the goals we set for this month:

Read more ...


Report - June 2015

With the Write the Docs conference wrapped up in May, we shifted our focus back to Read the Docs for the remainder of May and June. Following our post on contract positions available with Read the Docs, we hired two contractors to work with us and focus on support and stability for readthedocs.org. Gregor Müllegger will be working on support and development, and Andrew Kreps has helped us on building and improving our operations infrastructure.

Read the Docs had the following major updates in June:

Read more ...


Fundraising Wrapup

First off, a big ol’ thank you is in order for everyone that helped support us. You all helped us hit our funding goal, and with time to spare. We’re humbled to have such an abundance of support, and to know so many people share our vision for great documentation.

Really, thank you all. ❤

Read more ...