Introduction to Read the Docs to simplify project documentation

In the Doc Dish section, we’ve often focused on writing documentation, but that’s not all. Because what good is it to a writer if he writes the whole document and has no readers? Once the documentation is written, it must arrive in front of the user to be read. For anything beyond simple readme files, this can be a challenge; documentation writers often need design infrastructure, hosting, search tools, and more. A project aims to make this a little easier.

Read the Docs is an open source project (under MIT license) that started at Django Dash 2010. The goal of the project is to improve the quantity and quality of documentation by reducing barriers. Although Read the Docs can’t write your documentation for you, it automatically handles the build from your source code management system. Documents are rendered in HTML and PDF format and full-text search is included.

Thousands of open source projects host their documentation on the Read the Docs site, and others use Read the Docs code to self-host. In addition, the team has launched a paid service for commercial and private use.

Reading the documentation solves so many problems, why would not do you use it? The main reason would be if you write your documentation in something other than restructured text. Read the Docs uses Sphinx for rendering, so until Sphinx supports other markup languages, your options are limited. All hope is not lost: the Read the Docs team has added CommonMark support to Sphinx, so you can add whatever language you need, if you want.

Of course, there are other ways to contribute to Read the Docs. The most pressing need is for additional people in the support and operations teams. Support team members help users diagnose and resolve issues through GitHub issues. The operations team takes turns to ensure the operation of the site 24 hours a day, 7 days a week. More information about these contributions is available on the Team page. Financial support is also possible through recurring Gold subscriptions or one-time donations to the sustainability campaign.

With Read the Docs, you have no more excuses not to publish your documentation where users can find it.

Do you have experience reading documents to share? Let us know in the comments, or submit a Doc Dish article proposal.

Sam D. Gomez