Easy documentation for open-source projects

March 19, 2015

A few weeks after Clastic’s first alpha release, one of the major requirements was documentation.

I looked into the options and found lots of options. I must say I didn’t try all of them, but I looked at the pros and cons of the popular ones.

Read The Docs

I chose Read The Docs. The main two reasons I went with Read The Docs is that they support branch based documentation versioning and you don’t have to worry about documentation layout.

RTD support Sphinx docs written with reStructuredText and Markdown docs written with Mkdocs. I went with `rst` so I could make a difference between the library documentation like README and CONTRIBUTION information and the actual documentation.

My documentation is located in the `docs` folder. This allows for a centralized repository for people to contribute.

RTD gives you nice extra’s like search, automatic builds, …

If you want to learn more. Have a look at their own documentation.

comments powered by Disqus