Posts from Portland, Oregon

Read the Docs newsletter - January 2024

We have shipped New improvements to redirects, making our redirects much more powerful and flexible.

We have shipped an updated approach to notifications. Currently there isn’t much UX difference, but as we move forward with this project we will be able to provide more context and control to users.

Read more ...


Read the Docs newsletter - December 2023

We have shipped single version projects to allow projects to be versioned without having translations. This is a long-requested feature that we’ve excited to ship based on our Proxito refactor work.

We improved our webhook security by requiring a secret to be configured for all webhooks. This will help prevent malicious actors from triggering builds and other actions.

Read more ...


Read the Docs newsletter - November 2023

Work continues on hardening Addons, our new in-documentation JavaScript client that supports all documentation tools. We’re looking for people in the community to test out this new functionality, and will be expanding access in the near future.

Python 3.12 is now supported on builds, and is the default version used when you specify build.tools.python: 3 in your configuration file.

Read more ...


Read the Docs website migration to about.readthedocs.com

Read the Docs is in the process of migrating our primary marketing website to a single site: https://about.readthedocs.com. The new site offers users more information about our products and their features, in a combined presentation of what was previously divided between two websites (Read the Docs Community (readthedocs.org) and Read the Docs for Business (readthedocs.com)). The new site will also serve as a single entrypoint for users that are logging in to Read the Docs accounts. There has been a good deal of confusion around our two sites, and this change makes it more clear which site you’re going to.

Importantly, we are keeping both our Community and Business sites separate for logged in users. There are no changes in our commitment to offering free hosting for open source, or the separation of infrastructure for Business customers.

Read more ...


Read the Docs 2021 Stats

2021 continued in the realm of being a tough year. That said, Read the Docs had a lot of good things happen this year.

We did a majority of the work on our CZI grant, grew our team from 5 to 8, and continued to grow our EthicalAds network & Read the Docs for Business. It’s been another year of steady growth, and we hope to continue that into 2022.

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


Read the Docs 2020 Stats

2020 was a rough year for everyone, including our team. We managed to make it through, and continue to have 5 folks working full-time to make Read the Docs better for you.

We are going into 2021 with a new grant, which will require us to do some hiring. We also launched our EthicalAds network, which is bringing our approach to sustainability to the tech community as a whole.

Read more ...


Announcing Chan Zuckerberg Initiative Grant to Expand the Interoperability of Scientific Documentation

We’re excited to announce that Read the Docs has received a $200,000 grant from the Chan Zuckerberg Initiative’s Essential Open Source for Science (EOSS) program. Read the Docs is the largest open source documentation hosting platform in the world. We provide hosting for many scientific software packages, including some that have received EOSS funding in the past. You can read more about this round of grants in the official announcement.

Our grant has two parts:

Read more ...


Shipping a CDN on Read the Docs Community

You might have noticed that our Read the Docs Community site has gotten faster in the past few weeks. How much faster likely depends on how far away you live from Virginia, which is where our servers have traditionally lived.

We have recently enabled a CDN on all Read the Docs Community sites, generously sponsored by CloudFlare. This post will talk a bit more about how we implemented this, and why we’re excited about it.

Read more ...


Read the Docs 2019 Stats

2019 was another good year for Read the Docs. We continue to have a team of 5 folks working on the project, and we’ve rolled out a number of new features for the year.

Here are our stats for the past year, which we’ve published since 2013. This is part of our effort to be transparent in our organization, as well as our source code.

Read more ...


Read the Docs Offsite 2019

The Read the Docs team just finished our first offsite ever in April of 2019. We all gathered together in person for the first time, and talked about the future of the project.

A picture will show this better than I can:

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


Read the Docs 2018 Stats

2018 was another good year for Read the Docs. We’ve settled into a sustainability model that is working for us, and have a team of 5 folks working full-time on the project.

Here are our stats for the past year, which we’ve published for the past 6 years. This is part of our effort to be transparent in our organization, as well as our source code.

Read more ...


Ethical Advertising Works

It has been two years since we first launched ads on Read the Docs. We figured it was time to report on the results that we’ve seen, and say thanks to those who have helped us along the way.

To put it simply:

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


Read the Docs 2017 Stats

2017 was a good year for Read the Docs. We’ve settled into a sustainability model that is working for us, and have started to grow our team to be able to better support the community.

Here are our stats for the past year, which we’ve published for the past 5 years. This is part of our effort to be transparent in our organization, as well as our source code.

Read more ...


MOSS Final Report

Last year, we were given a MOSS Award to work on improving the Python documentation ecosystem. We announced the initial deployment last November, and this is the retrospective post about how the project as a whole went.

This work is live at http://www.pydoc.io/ and on GitHub:

Read more ...


Ads on the Alabaster Theme on Read the Docs Community Sites

We’ve been running our ethical advertising campaign for over a year now, and it is starting to show success on making Read the Docs more sustainable.

Over this time, we have only been running ads on Read the Docs themed projects. The primary reason for this is making sure that our display of ads is consistent and doesn’t negatively impact the user experience. We’re trying hard to build a sustainability model that respects our users, and making sure things are well designed and unobtrusive is an important part of this.

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


Uniregistry sponsors Read the Docs and Open Source

Today we’re excited to announce an important sponsorship partner in our Ethical Advertising campaign: Uniregistry. Our goal with our ethical advertising program is to provide important funding for open source, and show that it can be done ethically – without tracking our users and only offering ads from relevant partners.

Domain registration was identified early as a natural partner to our program, because it sits in the stack of necessary infrastructure for all of us that work on making the internet. We wanted the right partner, because historically we feel that domain registration companies have had awful UX. We’ll cover a few of the criteria we used to reach the conclusion to partner with Uniregistry.

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


Read the Docs 2016 Stats

Congrats, you made it through 2016! Read the Docs has been rolling along, and we’ve had another interesting year as well.

For a quick summary:

Read more ...


Announcing pydoc.io beta

Today we’re excited to announce our latest project: https://pydoc.io. This work was made possible by the MOSS Grant from Mozilla. Thanks to Mozilla for funding our time building this wonderful community resource.

Running Read the Docs, we’ve always been proud of the documentation tooling that the Python community has. We prioritize prose over API documentation listings, and generally have a high standard of documentation in our projects.

Read more ...


Running ads with Sentry

We’re excited to announce our first partner in our Ethical Advertising campaign: Sentry.

Sentry was a natural first partner, both because they have a long history supporting and contributing to the open source community, and because they also strive to support open source while building a sustainable business around their project.

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


Advertising on Read the Docs Community Sites

On Monday, we enabled an ad space on documentation pages hosted on readthedocs.org. We have tested the ad space in the past, and had followed up with a discussion of the implications of advertising. The space was meant to be totally unobtrusive to the browsing and usage of documentation pages, and doesn’t enable third-party tracking of users in any way. This is all in an effort to help raise funds to support continued support and maintenance on the project, and ensure free and open documentation stays available.

Read the Docs is a massive project, and requires a large amount of work to keep running and support. We receive support requests and must tend to the operations of the servers on a daily basis. Neither of these tasks lend to volunteer contributions, they both require dedicated support roles for such a large site. I’ve personally been wearing a pager in support of the project for over 4 years, all on a volunteer basis.

Read more ...


Read the Docs 2015 Stats

2015 has been another great year for Read the Docs. We’ve addressed some long-standing issues like not having Markdown support, and built a number of wonderful tools for the documentation community.

You can always see our stats for the last 30 days.

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


Read the Docs & Sphinx now support Commonmark

Read the Docs is built on top of Sphinx, which has always relied on reStructuredText as an input mechanism. We have long heard from folks that they want to write documentation in Markdown, as well as RST.

Today we are announcing that this is now possible! With the standardization of Markdown into Commonmark, we have the ability to support a markup language with a proper spec. recommonmark is the bridge that allows Commonmark to be used inside Sphinx. This allows you to use both RST and Commonmark inside of your Sphinx project.

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


Read the Docs is hiring!

Thanks to our successful fundraiser, we have the ability to pay people to work on Read the Docs.

We have two positions that we are looking for:

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


Read the Docs 2014 Stats

2014 has been another banner year for Read the Docs. The project has been steadily growing in the open source ecosystem, expanding a good deal outside of the Python community. We have built a bunch of fantastic new features, and continued improving the documentation experience for the open source world.

You can always see our latest 30 days stats at http://www.seethestats.com/site/readthedocs.org.

Read more ...


User-defined Redirects

Today we are announcing User-defined Redirects for Read the Docs. This has been a long requested feature that should cut down on 404’s when migrating your documentation.

Read the Docs has long had Redirects, but they are managed automatically for only certain use cases. This change allows users to control a specific set of common redirects.

Read more ...


Badge Support

Documentation is an often overlooked part of a software project. Today we are releasing badges for your docs, so that people can easily see that your docs are up-to-date.

The main use of badges is to show the status of your project’s build. They will display in green for passing, red for failing, and yellow for unknown states.

Read more ...


Welcome

Welcome to the Read the Docs blog.

We will be doing regular feature announcements on the blog as we build them. There are also a number of recently released features that we’ll highlight there as well.

Read more ...


Read the Docs 2013 Stats

2013 has been a big year for Read the Docs. Our mission is to make documentation hosting easier, with the overall goal of increasing the quality of documentation in the programming world. I believe that we have been doing good work towards that goal, and I want to share some numbers to reflect our progress.

Our community has been great this year. I have been really happy to see a few people submit multiple patches and features. This year, we had:

Read more ...


A New Theme for Read the Docs

We have been hard at work improving Read the Docs over the past month. A large amount of back end work has been going on, and now we have a brand new documentation theme to showcase it.

We have looked at how people use documentation, and built a beautiful and highly functional new interface for browsing documentation. We created a solution that looks great and works well.

Read more ...