Using reStructuredText files

Plain text, by definition, is limited in what information it can provide; that is, there is no metadata inherent in a text file (apart from what is provided by the filesystem). In other words, there is no way to bold, italicize, or otherwise augment raw text, to provide some sort of contextual information.

A number of markup languages have been developed over the years, with HTML being a prime example this. However, HTML is a little heavy for in-code documentation purposes. Something more like Wikitext (https://en.wikipedia.org/wiki/Help:Wikitext) would make more sense, as it uses simple ASCII characters to provide context to raw text. Hence, PEP 287 proposes the reStructuredText (reST) markup be used for structured text documentation within Python docstrings, PEPs, and other documents that require structured markup. Of course, plain text docstrings are not deprecated; reST simply provides more options, for developers who want to be more expressive in their documentation...