Quite a few re-usable Django apps and Python modules come with documentation in text files ending with a .rst extension. The formatting in them is odd, but they’re more-or-less readable.
Image may be NSFW.
Clik here to view.
To this day, I haven’t encountered a single package that explained why docs were formatted this way. I knew there had to be an explanation, but hadn’t gotten around to looking it up, and basically just waded through. Finally went looking for an answer today. Turns out .rst files use a simple markup syntax called restructured text and you can generate nicely formatted HTML (and other documentation formats) out of them if you have python’s sphinx module installed. For the benefit of future googlers, here’s how to get up and running quickly:
$ pip install sphinx
$ cd docs
$ mkdir out
$ sphinx-build . out
Now take a look in the “out” directory and you’ll find the same set of files as a collection of handsomely formatted HTML docs.
Image may be NSFW.
Clik here to view.
Sphinx goes pretty deep, and I’m looking forward to exploring it for future documentation projects. For now I’m just happy to have an alternative to squinting.
