Mastering Object-Oriented Python - Second Edition

Learning RST

One way to build skills in RST is to install docutils and use the rst2html.py script to parse an RST document and convert it to HTML pages. A simple practice document can easily show us the various RST features.

All of a project's requirements, architecture, and documentation can be written using RST and transformed into HTML or LaTeX. It's relatively inexpensive to write user stories in RST and drop those files into a directory that can be organized and reorganized, since stories are groomed, put into development, and implemented. More complex tools may not be any more valuable than docutils.

The advantage of using pure text files and the RST markup is that we can easily manage our documentation in parallel with our source code. ...