This week, we'll be moving the Tripal documentation over to ReadTheDocs. I've already put the Tripal DevSeed documentation online.
This post will talk about the reasons for this decision, and a quick "how to" guide.
Documentation is important. It tells users how to use our product, and developers how to read our code. In the past, I've written my documentation out in markdown and included it alongside the code. This approach still makes sense for small projects, and it gets built nicely by GitHub on the repository.
For larger projects, such as Tripal, the real documentation is hosted on a drupal site at tripal.info. There is a full content management system for creating new posts, managing privileges, uploading images, linking documents, etc.
ReadTheDocs uses Sphinx to build a website in a Continuous Integration setup. When new code is pushed to GitHub, the documentation website as defined by sphinx is built, and the "live" documentation website is updated.
This has several advantages:
These are all huge points. It's actually quite hard to remember to update the documentation when its on a separate website. You also don't have to remember to re-build the website, ReadTheDocs rebuilds it when you push new code and documentation.
It's very simple: check out the official guide.
The abbreviated version is:
make htmlin the
docsfolder to build your site for testing purposes
RST format. It might seem a little more complicated than markdown (and it is), but its also more powerful, so I feel its worth the work.
Link documents to your
index.rst and Sphinx will build you a searchable site with nicely formatted navigation.
ReadTheDocs also provides some really awesome versioning tools, allowing you to post releases of the documentation so users can go back and find older documentation with almost no effort on your part.
We currently have ReadTheDocs up for the following projects: