Improved documentation

[josiahjohnston]

Our documentation needs a lot of improvement. Extensive documentation is embedded in docstrings of most modules and functions, but the pydoc results are crap. When learning the model, the Switch-Mexico team chose to read the code directly instead of the pydoc stuff and re-write the documentation in LaTeX.

Our working plans for cleaning this up are:

• Set up Sphynx, and write rst documentation source that is independent of the code. Portions of the docstrings will be migrated over. This will pave the way to writing more how-to-guides and high-level documentation that can include equations and figures as needed.
• Move the component documentations from the pydoc string of their module's define_components() to attributes of the components themselves. See pull request #57 for some discussion. Write some new code to construct a model, then introspect it to describe each component and its documentation (possibly including equations). The module- and component-level documentation could either be compiled into a rst file or otherwise passed into Sphynx.
  • Use the "doc" attribute as a very short text label (<= 1 sentence). This gets printed out in Pyomo dumps & pprints.
  • Add a "rst_doc" attribute as succinct documentation (<= 1 paragraph). This could include formatted equations, but no references to external files/figures. Anything more extensive needs to go in its own rst file.
  • Add a "units" attribute to assist people in manual unit checks. In an ideal world a Pyomo utility library could introspect each equation and ensure that units cancelled out appropriately.
• Use Sphynx's auto API document engine to scan the directories and summarize the API (the remaining pydoc strings, modules, interfaces, etc.)

Note, the component documentation could either be in the doc argument of its definition, or assigned to an arbitrary attribute immediately after the definition. I'm pretty sure we will have to write some custom code to inspect the pyomo model, so assigning our extra documentation to our own extra attributes seems like a fairly clean solution.

[josiahjohnston]

Interim sources of well-formatted documentation:

Switch 2.0: A modern platform for planning high-renewable power systems and the appendix with more equations and tables linking mathematical symbols to names in the source code.