Writing documentation with RST markup
While Python code should be beautiful and informative, it doesn't easily provide background or context to show why a particular algorithm or data structure was chosen. We often need to provide these additional details to help people maintain, extend, and make effective use of our software. While we can include a lot of information in a module docstring, it seems best to keep docstrings focused on implementation details, and provide the additional material separately.
We can write additional documentation in a variety of formats. We can use a sophisticated editor with complex file formats, or we can use simple text editors and plain text format. We can even write our documentation entirely in HTML. Python also offers a hybrid approach—we can write using a text editor with simplified ReStructuredText (RST) markup, and use the docutils tools to create nice-looking HTML pages or LaTeX files suitable for publication from that markup.
The RST markup...
