Recent posts

  • 01 July - 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.

  • 18 May - 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.

  • 14 May - 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.

  • 04 May - 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.

  • 28 April - 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.

  • 29 August - 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.

  • 27 August - 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.

  • 14 August - GSOC 2019: Autobuild Documentation for Pull Requests

    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.

  • 13 August - GSOC 2019: Improved Search Results and Search As You Type

    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.

  • 10 July - 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.