Read the Docs Blog - Posted in 2014

Read the Docs 2014 Stats

2014-12-31T00:00:00Z

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.

Note

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

Our post from 2013 is also available here: https://blog.readthedocs.com/read-the-docs-2013-stats/

Community

This year, we had:

46 people who committed code (+17% from last year)
1253 commits (+127%)
500 issues - 376 closed, 130 open (+84%)

We have over doubled the commit count from the previous year, along with having almost double the issues. Our contributor base has grown slowly, but not nearly at the rate of issues and user growth.

A big part of that is the addition of Anthony to the core team. He has been a great help, and done lots of good work on the project.

Page Views

Our stats:

110 Million Page Views (+70%)
24 Million Unique Visitors (+85%)

Page view growth has been steady again this year. It’s great to see so many people reading documentation that we are hosting.

With an average time of 3 minutes per page, this means users have spent nearly 600 years [1] reading documentation on Read the Docs this year. I can only imagine how much development time has been saved.

Note

I believe this makes Read the Docs the biggest documentation hosting website in the world. Pretty neat.

A picture shows more than the words do, I think. Here is our weekly graph for the year:

Site Stats

The stats, in total numbers:

15128 projects (+90%)
22263 users (+90%)
2053616 builds (+97%)

Read the Docs has some high profile projects that push a lot of traffic. There are however thousands of smaller libraries and projects that fill out that full range of documentation that we host.

Funding

Our hosting costs are sponsored by Rackspace, which is fantastically generous of them.

Development on Read the Docs is funded by the community on Gittip. I am very grateful for the support that the community has given the project over the years. We haven’t been promoting the sponsorship on Gittip, so the numbers there have gone down.

We are looking at more funding options in the new year, more on that soon :)

The stats:

$100/wk (-40%)
100 people giving money (-12%)

Conclusion

2014 has been an amazing year for Read the Docs. We have continued growing and serving more traffic.

We are working on a number of new features to expand the user base, and make the site more approachable. We look forward to continuing to improve the documentation ecosystem in the new year.

[1]	2min 51sec * 108,801,906 views / 525,600 minutes/year = 589.6 years

User-defined Redirects

2014-08-22T00:00:00Z

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.

Prefix Redirects

The most useful and requested application of redirects was to migrate to Read the Docs from an old host. You would have your docs served at a previous URL, but that URL would break once you moved them. Read the Docs includes a language and version slug in your documentation, but not all documentation is hosted this way.

Say that you previously had your docs hosted at http://docs.example.com/dev/, and you move docs.example.com to point at Read the Docs. Users will have a bookmark saved to a page at http://docs.example.com/dev/install.html, a URL that no longer exists.

You can now set a Prefix Redirect that will redirect all 404’s with a prefix to a new place. The example configuration would be:

Type: Prefix Redirect
From URL: /dev/

Your user’s query would now redirect in the following manner:

docs.example.com/dev/install.html ->
docs.example.com/en/latest/install.html

Where en and latest are the default language and version values for your project.

Page Redirects

A more specific case is when you move a page around in your docs. The old page will start 404’ing, and your users will be confused. Page Redirects let you redirect a specific page.

Say you move the example.html page into a subdirectory of examples: examples/intro.html. You would set the following configuration:

Type: Page Redirect
From URL: example.html
To URL: examples/intro.html

Sphinx Redirects

We also support redirects for changing the type of documentation Sphinx is building. If you switch between HTMLDir and HTML, your URL’s will change. A page at /en/latest/install.html will be served at /en/latest/install/, or vice versa. The built in redirects for this will handle redirecting users appropriately.

Implementation

Since we serve documentation in a highly available way, we do not run any logic when we’re serving documentation. This means that redirects will only happen in the case of a 404 File Not Found.

In the future we might implement redirect logic in Javascript, but this first version is only implemented in the 404 handlers.

Feature Requests

This is an initial attempt at redirects. We have some plans to improve this, but get in touch with us if you have ideas for improving the feature.

Feel free to file an issue, or you can always reach us at readthedocs@gmail.com.

Badge Support

2014-08-14T00:00:00Z

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.

Status Badges

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.

Here are a few examples:

You can see it in action in the Read the Docs README. They will link back to your project’s documentation page on Read the Docs.

Project Pages

You will now see badges embedded in your project page. The default badge will be pointed at the default version you have specified for your project. The badge URLs look like this:

https://readthedocs.org/projects/pip/badge/?version=latest

You can replace the version argument with any version that you want to show a badge for. If you click on the badge icon, you will be given snippets for RST, Markdown, and HTML; to make embedding it easier.

If you leave the version argument off, it will default to your latest version. This is probably best to include in your README, since it will stay up to date with your Read the Docs project.

Design

We have often wondered what we might make our badges look like. Luckily, there is a developing standard and service to support badges. http://shields.io is what we’ll be using to generate our badges, and they look beautiful.

Feature Requests

This is an initial attempt at adding badges to Read the Docs, it’s a feature we’ve wanted to add for some time. We have some plans to improve badges further, but be sure to get in touch with us if you have any feedback on how you would like to see badges used.

Feel free to file an issue, or you can always reach us at readthedocs@gmail.com.

Welcome

2014-08-07T00:00:00Z

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.

We have back ported some old blog posts from Eric Holscher’s blog that were about Read the Docs, so that you can find them a bit easier in the future.

Thanks for stopping by. We’ll have some awesome new features for you next week.