All Posts

Read the Docs newsletter - December 2021

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.

We successfully deployed mitigation measures against spam, and we are happy to report that the amount of abusive projects has dramatically decreased.

Announcing Embed API v3 and sphinx-hoverxref 1.0

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.

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.

Read the Docs ❤️ Jupyter Book

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.

Read the Docs newsletter - November 2021

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.

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.

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?

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

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.

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.

Read the Docs newsletter - October 2021

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.

We have resumed sending our blog updates by email. You can subscribe to our newsletter so you don’t miss them.

Read the Docs newsletter - September 2021

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.

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

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 the Docs newsletter - August 2021

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.

We have a new team member! Ana just joined us as Frontend Developer in the context of the CZI grant we were awarded to work on our JavaScript documentation embedding client and the Read the Docs redesign and UX.

Read the Docs newsletter - July 2021

Welcome to a new 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.

Eric presented the history of the company at the Upstream 2021 conference along with ideas for open source sustainability. You can read more about it in our recent blog post.

Early 2021 talks and podcasts from Read the Docs

During the first half of 2021 several team members of Read the Docs have talked about the company in podcasts and online events. If you want to learn more about our company directly from the people that are a core part of it, and hear our thoughts on other topics like open source sustainability and developer advocacy, this blog post is for you.

Eric was the special guest of Sustain back in February, “a podcast about sustaining open source in the long haul”. Eric started by telling the story of how he and Anthony co-founded Read the Docs, talked about the Write the Docs community, described the challenges of launching EthicalAds in 2020, and discussed the opportunities of using ethical advertising to fund open source projects.

New release of sphinx-hoverxref with support for intersphinx

10 June 2021
Juan Luis Cano Rodríguez
Madrid, Spain
czi grant czi-grant embed sphinx-hoverxref

We have released version 0.6b1 of sphinx-hoverxref, a Sphinx extension that shows a content preview of a cross-reference.

This extension is an essential part of the work we are doing to improve interoperability of documentation in general, and scientific documentation in particular, thanks to the CZI grant we received last year.

Read the Docs newsletter - June 2021

Welcome to a new edition of our monthly newsletter, where we openly 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.

We applied to the next round of the CZI Essential Open Source Software for Science! Our proposal is even more ambitious than the previous one, and we are excited about the possibilities for our users if we get accepted. The funding would cover 2 years of work, starting in 2022.

Install custom operating system packages (apt)

We are thrilled to announce that now Read the Docs users can declare custom operating system packages in their project configuration that will get installed in our Ubuntu-based builders using apt. This has been a long awaited feature, and we think it will simplify the configuration of many projects, especially scientific ones.

The Ubuntu images used by our builders contain lots of preinstalled system packages that we ship to all the projects to make the most common use cases possible. This includes compilers, development headers of common libraries, and others.

Read the Docs newsletter - May 2021

Welcome to a new edition of our monthly newsletter, where we openly 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.

The team keeps growing! Ra will join us next week to do account management for EthicalAds.

Read the Docs newsletter - April 2021

This is the first of our monthly newsletters, in which we would like to openly share with you the most relevant updates of Read the Docs, offer a summary of what new features we shipped to our users during the previous month, and share what things we will be focusing on in the near future.

We have a new colleague! Juan Luis will be working with us as Developer Advocate, with a focus on fulfilling the goals of the CZI grant we were awarded, improve our public facing documentation, and spread the word about our service.

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.

API v3 is now stable

We are excited to announce that our API v3 has reached a stable release, and is now available for all Read the Docs users. Since we announced the API v3 beta, we have been adding extra functionality and bug-fixing minor issues based on user feedback.

The new API v3 is not a fully replacement (yet!) of API v2, but we highly recommend using API v3 for all the new integrations. API v2 will be deprecated soon, though we don’t have a firm timeline for deprecation. We will alert users with our plans when we do.

Read the Docs Community downtime due to migrations to AWS

Update: The migration was successful and the site has been fully restored as of 4PM PST.

We wanted to make you aware that on Friday, February 12th at 1pm PST (4pm EST, 21:00 UTC), Read the Docs Community (readthedocs.org) will be having a scheduled dashboard downtime of approximately 4 hours.

Pull Request Builders available for all users

27 January 2021
Eric Holscher
Bend, Oregon
pr-builder continuous-documentation feature

We’re excited to announce that Pull Request building is now available for all Read the Docs users. We have been working on this feature for over a year, and having it available for all our users is a major milestone.

This feature allows users to confirm documentation builds correctly for all of their commits, not just ones merged into branches that are activated on Read the Docs. This moves documentation into your continuous integration pipeline, and improves the workflow for everyone working on documentation.

Read the Docs for Business Maintenance Window - February 5

Update: This maintenance window has concluded at 5:40 PM PST.

We wanted to make you aware that on Friday, February 5 at 5:00pm PST (8:00pm EST, Saturday 01:00 UTC), Read the Docs for Business (readthedocs.com) will be having a scheduled downtime of approximately 2 hours.

Read the Docs is hiring for multiple positions

Read the Docs received a grant to support scientific software at the beginning of this year. As part of this, we are hiring for two new positions related to the grant work:

A frontend developer with design skills

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:

Advertising update and open sourcing our ad server

It’s been a while since our last advertising update and it felt like a good time to talk about what’s working with our advertising model and how things are getting better.

In our 2019 stats post, we broke out our advertising revenue which was fairly flat year over year. The way our ad business is structured, our revenue mostly grows with increases in traffic and Read the Docs is mature enough that it isn’t doubling in size every year.

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

Automation Rules

A time ago we introduced a new feature to help users to automate some tasks on Read the Docs. Automation rules.

If you manage a project with several versions, you may have noticed that Read the Docs doesn’t always activate your new versions [1]. If you require to do any action over a new version, you’ll need to log in your Read the Docs account and manually do so.

Better support for scientific project documentation

In the past year, we’ve been having issues when building projects’ documentation using conda. Our build servers were running out of memory and failing projects’ builds. Read the Docs has this memory constraint to avoid misuse of the platform, causing a poor experience for other users.

Our first solution was a dedicated server for these kind of projects. We would manually assign them to this server on user requests. This workaround worked okay, but it involves a bad experience for the user and also us doing a manual step each time. Over time, we hit again the same issue of OOM, even giving all the memory available to one project to build its documentation. After some research, we found that this is a known issue in the conda community and there are some different attempts to fix it (like mamba). Unfortunately, none of them became the standard yet and the problem is still there.

Optimizing Sphinx Documentation for Search Engines

Recently, we published a guide on SEO for technical docs with the goal of helping documentation authors and project maintainers create docs so that end users can find what they’re looking for easier.

One developer asked me point blank after I mentioned our new guide, “Hasn’t Google closed most of the loopholes that sites use to rank better?”. I’ve heard this opinion from a few technologists before so I wasn’t too surprised. Moz.com, an authority on search engine optimization, makes a distinction between what they call black hat SEO and white hat SEO to differentiate between these “loopholes” and more useful site improvements that help SEO.

Announcing API v3 Beta

In the last months, we have been working on making our API better. Considering the limitations of our current REST API v2, we decided to make a bigger step forward and create a new API v3, putting the focus on the use cases we heard about from existing users.

Compared to API v2, our new API v3 has some big differences that make it more user-friendly and useful.

GSOC 2019: Autobuild Documentation for Pull Requests

14 August 2019
Maksudul Haque
Dhaka, Bangladesh
gsoc pr-builder continuous-documentation feature

Building documentation for pull requests is one of the most requested features of Read the Docs. Similar to how a continuous integration system runs a test suite on every pull request, this change would build the documentation for each pull request and send build status notification to the providers’ Status API (e.g. Github Status API). This will let users check if the documentation build passed and also how the documentation looks before merging it to master.

As a student of Google Summer of Code (GSoC) 2019, I (Maksudul Haque) was tasked with building this feature. The main goal of my project was to make it possible to build documentation whenever a pull request was created, and send build status notification to the Providers’ Status API.

GSOC 2019: Improved Search Results and Search As You Type

13 August 2019
Vaibhav Gupta
Lucknow, India
gsoc search feature in-doc-search analytics

Giving users the ability to easily find the information that they are looking for has always been important for Read the Docs. This year, I, Vaibhav Gupta, took the opportunity provided by Google Summer of Code to improve the search. The main goals of my GSoC project were:

to make a Sphinx extension to provide “search you type” experience to the users.

Adding Custom CSS or JavaScript to Sphinx Documentation

In the Read the Docs documentation, we have a number of how-to guides to help people solve specific problems with Sphinx and Read the Docs. By far our most popular guide is on adding custom CSS and JavaScript to Sphinx.

In some older versions of Sphinx, this process was a little more challenging and it wasn’t as easy to figure out how to do it from the Sphinx docs. Sphinx 1.8 really streamlined this process especially for the simple cases.

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:

New Ad Format Coming to Read the Docs Community Sites

We view our ad program as a way to keep Read the Docs itself sustainable, and to use it to better support the community. Advertising has allowed us to have full-time employees adding new features and responding to issues in our issue tracker. We have also been able to share thousands of dollars with the open source community via our revenue share program and grants.

Currently, about 30% of our site traffic does not have any advertising. When we first launched ethical advertising in 2016, we launched only on specific documentation themes. We purposely did this slowly to make sure our ads look integrated with Read the Docs and less obtrusive to users.

Ad Funding at Read the Docs and What’s Next for Ethical Advertising

11 June 2019
David Fischer
San Diego, CA
advertising business sustainability ethical ads

It has been three years since we first launched ads on Read the Docs and while we gave a limited update in our 2018 stats, we figured it was time to give an update on ethical advertising and how it is working.

Our ethical advertising model is still going strong. We proved that it is possible to build a business model on top of advertising without resorting to user tracking. Unlike most other ad-supported sites, we show advertising based on the context of the page, not by creating behavoral profiles of large numbers of individual users. If you are browsing documentation for a Python project, you might see a relevant ad about Python. It’s that simple and it works.

New Configuration File

We are happy to announce the new version of the Read the Docs configuration file (v2).

If you are a recurrent Read the Docs user, chances are that you’ve configured your projects using a .readthedocs.yml file.

Tips for Getting a Developer Interview

Over the last month, the Read the Docs team conducted 30-40 customer development interviews with hiring managers and recruiters at companies ranging from 5-person companies to the biggest names in tech. We wanted to learn more about hiring processes at various companies with the ultimate goal of building a product to help companies find developers.

Last time, we covered some tips for hiring managers based on what companies told us they were doing. This time, we put together tips for candidates looking for their next job based on insights we heard from hiring managers.

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.

Improved Search

Have you ever struggled with a poorly documented software project? What about a well documented project but you can’t find the right section inside the docs? The Read the Docs core team has realized the importance of good search for documentation and got me to take the challenge as a Google Summer of Code student. The main goal of my GSoC project was to refactor the search code together with upgrading the backend search engine, as well as adding more features to our search functionality like exact match search, case insensitive search, search as you type, suggestions and more.

Google Summer of Code is a global program where students work with an open source organization on a 3 month programming project. The core team of Read the Docs proposed some Project Ideas, one of them was Refactor & improve our search code. I (Safwan Rahman) was keen to get my hands dirty with Elasticsearch and grasped the opportunity to do so by applying for this project and I got accepted.

Lessons From and For Hiring Managers

Over the last four weeks, the Read the Docs team did dozens of customer development interviews with engineering hiring managers. We wanted to learn more about hiring processes at various companies with the ultimate goal of building a product to help companies find developers. We talked to people looking for talent at five person companies all the way up to the biggest names in tech. In this post, I am going to cover some of the common things we heard from hiring managers and share some ways for hiring managers to improve their company’s process. In our next post in this series, I will have some actionable tips for job seekers based on the same interviews.

Since this is a long post, I figured I’d share some of the key takeaways:

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

Tips to Hire Developers with Read the Docs

Read the Docs is probably not the first place you think of if you are recruiting. However, over 7 million unique developers use Read the Docs each month from all over the world. We didn’t set out to build a better job board, but after a number of advertisers used our ethical ads for recruiting, we discovered that Read the Docs was a great place to find developer talent.

Developers are not always actively job seeking by browsing job boards or company careers pages. However, they are on Read the Docs reading about the libraries and frameworks they use. Even when people aren’t actively looking for a new job, many are open to exploring new opportunities.

Community Advertising

06 September 2018
David Fischer
San Diego, CA
advertising community updates community ads

As part of our ethical advertising model, Read the Docs gives away 10% of our ad inventory to projects, conferences, and other initiatives in the open source community. Many of these projects operate as Read the Docs did in the past with little to no income. These are not groups that traditionally have the resources to use paid advertising.

We have run ads for:

HTTPS for Custom Domains

Read the Docs hosts documentation for over 80,000 open source projects and over 2,500 of those projects are hosted on their own individual domains. Documentation hosted on *.readthedocs.io has supported HTTPS for a number of years, but one of our most requested features was to make HTTPS on other domains easy. Today we are happy to announce that Read the Docs supports HTTPS on custom domains!

Earlier this year, Cloudflare contacted us to support HTTPS for the thousands of open source documentation projects on their own domains. They generously provided us with their SSL for SaaS package to ease the integration on our side.

Planned Move to Azure

We wanted to make you aware that on Saturday August 18 at 10:00am PDT (1:00pm EDT, 17:00 UTC), Read the Docs will be having a scheduled downtime of approximately 4 hours.

To ensure the stability and performance of our system, we are performing this upgrade during the weekend which is our period of lowest usage.

Read the Docs Public API

Recently, we revamped Read the Docs’ public API. Previously, our latest API (v2) was used by our build processes but not heavily used by outside users.

As part of this process, we put effort into making sure the API is easy to use to access Read the Docs projects, builds, and versions, easier to filter builds and versions by a particular project, and that the documentation is up-to-date.

Do Not Track at Read the Docs

Today, we are pleased to announce that Read the Docs honors Do Not Track (DNT). DNT is a browser preference that requests that a user not be tracked across the internet while browsing the web.

While there isn’t a consensus on precisely what DNT should mean, we are following the Electronic Frontier Foundation’s (EFF) guidelines for Do Not Track as we believe that gives a good balance between the privacy expectations of users and the reality of running a business and keeping Read the Docs sustainable.

GDPR: What it means for Read the Docs

Your email inbox has probably been bombarded over the last few days and weeks with “Updates to our Privacy Policy”. These emails pertain to an EU law called the General Data Protection Regulation (GDPR) which comes into effect today.

The goal of the GDPR is to put users back in control of their data. It is an important step toward respecting users’ privacy. The days of collecting as much data on as many people as possible without consent and sharing it with anyone willing to pay for it are over.

Update on Ad Blocking and Acceptable Ads

21 May 2018
David Fischer
San Diego, CA
advertising sustainability business adblock

A few weeks ago, we shared about the challenge ad blocking presented to our sustainability and what we were doing about it. On May 4th, Read the Docs was added to the Acceptable Ads list meaning that our visitors running ad blockers who choose to allow unintrusive advertising will see our ads again. The impact to our ad views, clicks, and revenue was immediate.

Estimates around the web vary regarding what percentage of people run ad blockers and it varies heavily by industry. We discussed this figure a bit in our previous post.

Social Version Control Log in

Today we are announcing the ability to log in or sign up to Read the Docs with your favorite version control hosting services like GitHub, BitBucket, or GitLab. This was one of our most requested features and it has been something we’ve been meaning to launch for a long time.

For new users, the sign up process is significantly streamlined. There’s no new password to remember and when you’re ready to start building your docs, Read the Docs will be ready with a list of your repositories to get started.

Ads and Ad blockers

02 May 2018
David Fischer
San Diego, CA
advertising privacy sustainability business adblock

Last time, we shared how ethical advertising works to keep Read the Docs sustainable without creepy ad targeting. This time, we will share about one of our biggest challenges with advertising. At the beginning of April, Read the Docs was added to one of the most popular ad block lists: the Easylist.

Getting added to the EasyList had a significant and immediate impact on the bottom line at Read the Docs. Right around April 1, 32% of our ad views simply vanished. At first, we thought we had done something horribly wrong but then we discovered that this was due entirely to ad blocking. Our actual traffic wasn’t down at all.

Ethical Advertising Works

16 April 2018
Axel Sepúlveda
Portland, Oregon
advertising business sustainability ethical ads

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:

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

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:

Ads on the Alabaster Theme on Read the Docs Community Sites

16 June 2017
Axel Sepúlveda
Portland, Oregon
advertising community updates community ads

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.

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.

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.

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.

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

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.

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.

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.

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

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.

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?

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:

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:

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

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

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.

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.

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

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.

Subscribe to our mailing list

Thank you!

Follow us