When doing documentation work, be it regular documentation, how-tos, or wikis, I always use reStructuredText syntax if I have the chance, so eventually if I have to provide documentation in other forms, I can convert source text into other formats like HTML or PDF seamlessly. This same rule applies to wikis, which are, after all, a collaborative way of producing documentation.

On GitHub wikis are also git repositories. So you can clone it and work like any other repo. Great, isn't it?

We aware that file extensions must be .rest in order to github to recognize them as reStructuredText. My vim configuration highlights rst syntax if editing a file with .rst but not .rest. I wonder if an official extension name exists for rst files. I renamed Home.rest to Home.rst and still works. Sometimes I take things for granted without even trying. sigh.

Before commiting changes to a document, it is cool to check that the syntax is right. Otherwise, you will end up littering your commit log with minor changes and fixes. Below I explain how to clone and use reStructuredText to work with it in an isolated python environment using virtualenv and virtualenvwrapper. I don't give instructions on this post on how to install them, sorry.

First, create a new virtual environment, and install the docutils python library (which contains the rst code):

mkvirtualenv --no-site-packages rst
pip install docutils

Once you have done your changes to a document, before commiting, check that the syntax is still valid and the changes you have made are right (sometimes we forget to link something, or make text bold instead of cursive, etc). What I do is create HTML from the source, so I can see clearly the results:

rst2html rstfile.rest > rstfile.html

If syntax is wrong, you will see that output informs you on the error type and the line you can found it. If everything is OK, open the HTML file and check it. For instance, in Mac OS X, I use the open command line to open the HTML file into my default browser:

open rstfile.html

That's pretty much everything. Whenever you got to edit the repo, don't forget to activate/switch to rst virtual environment every time you want to work with the wiki repository and rest:

workon rst