Better output via the RST markup
Our documentation can be much nicer if we use a more sophisticated toolset. There are several things that we'd like to be able to do, such as the following:
Fine-tune the presentation to include emphasis such as bold, italic, or color.
Provide the semantic markup for the parameters, return values, exceptions, and cross-references among Python objects.
Provide a link to view the source code.
Filter the code that's included or rejected. We can fine-tune this filtering to include or exclude a number of components and members: standard library modules, private members with a leading
__, system members with a leading__, or superclass members.Adjust the CSS to provide a different style for the resulting HTML pages.
We can address the first two requirements through more sophisticated markup in our docstrings; we'll need to use the RST markup language. We'll need an additional tool to address the last three requirements.
Once we start using more sophisticated markup,...
