Read the Docs Blog
Posts by Anthony Johnson
Build errors with docutils 0.18
- 02 November 2021
- Spokane, Washington
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?
Theme release 1.0.0rc1
- 23 August 2021
- Portland, Oregon
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:
Defaulting New Projects to Python 3
- 12 February 2019
- Portland, Oregon
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.
Incoming Webhook Deprecations
- 21 January 2019
- Portland, Oregon
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.
Python 3.6 Support
- 29 March 2018
- Portland, Oregon
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.
PyCon 2017 in Review
- 31 May 2017
- Portland, Oregon
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.
Release for May 12, 2017
- 12 May 2017
- Portland, Oregon
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.
Build Image Upgrades
- 14 February 2017
- Portland, Oregon
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.
Securing Subdomains
- 27 April 2016
- Portland, Oregon
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 the Docs Awarded Mozilla Open Source Support Grant
- 10 December 2015
- Portland, Oregon
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.
Securing Build Processes
- 30 September 2015
- Portland, Oregon
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.
State of the Docs
- 09 September 2015
- Portland, Oregon
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?
Report - July 2015
- 09 September 2015
- Portland, Oregon
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:
Report - August 2015
- 09 September 2015
- Portland, Oregon
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:
Report - June 2015
- 01 July 2015
- Portland, Oregon
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:
Fundraising Wrapup
- 01 May 2015
- Portland, Oregon
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. ❤