A new theme for Read the Docs

Read the Docs hasn’t changed much visually since it launched. We have had a default theme that is a slight change over the Sphinx theme. A few colors and a nice mobile interface was about it.

That is all about to change. We are proud to announce a new default theme for Read the Docs!

Creation Story

Dave Snider approached me about a month ago, offering to help improve the documentation ecosystem. He is a designer with an interest in documentation, and wanted to help out with Read the Docs.

He has built a fantastic new default theme for Read the Docs. We talked through a lot of the functionality of the site, and how people tend to use documentation. I think we have come up with a really great solution that will look great, but also work well.

Using it

There are 2 ways that you can use this theme on Read the Docs. The first is to simply leave your html_theme variable set to default. This is now the default Read the Docs theme. You can also set RTD_NEW_THEME = True in your project’s conf.py, and we will use our theme when building on Read the Docs no matter what html_theme is set to.

After you change these settings, simply rebuild your docs and the theme should update. More information about the theme can be found on the theme documentation page

If you want to continue using the old theme, simply set RTD_OLD_THEME = True in your conf.py.

Screenshots

Full site

The full documentation page is now beautiful and streamlined. We got rid of a bunch of the visual clutter and integrated a full-project Table of Contents on the left side. When you go into a specific page, the page-level contents get embedded in the sidebar as well. This allows you to keep context inside the documentation when you land on a page from a search.

Old

http://i.imgur.com/hWOnmKy.png

New

http://i.imgur.com/7oLntvR.png

Mobile

The new theme really shines on mobile. We provide a beautiful interface for phones and tablets, while staying completely functional.

http://i.imgur.com/29uEpVs.png

Conclusion

I think that this theme is a great addition to the documentation ecosystem. It is highly functional and beautiful, allowing users to easily navigate and find what they need.

We have a few more tricks up our sleves, but I believe the theme is ready to launch today. Over the next few weeks we’ll be adding a bit more functionality to it, which should be even more delightful.

I hope that you enjoy using it. If you have any feedback, please open an issue on GitHub for the repo.

If you want to support work like this, help fund development on Read the Docs on Gittip.