Update and improve documentation

[aerispaha]

The swmmio build pipeline integrates with sphinx to update the hosted documentation automatically for each new release, at swmmio.readthedocs.io. This is good. But this documentation has not been reviewed or updated for quite a while. This has left the documentation incomplete, and emphasizing features that may not be widely used or needed.

The overall goal of the documentation should be to make it as easy as possible for new users to get started with swmmio, and for experienced users to be able to understand some of the more advanced features. To that end, the README file should be refactored to

• emphasize the core features of swmmio (reading, writing, and visualization SWMM models),
• move the more esoteric features to separate pages (e.g. Flood Model Options Generation), and
• include all code snippets in the suite of doctests,
• fix typos and formatting issues (e.g. the table in the Basic Usage section)

Functions throughout the package should also be updated to include properly configured Numpy-style docstrings with doctests / examples embedded in all of the most widely-used public functions.

[dickinsonre]

Update and improve documentation - not to pick on you but I have been seeing that comment for 40+ years.

[aerispaha]

Update and improve documentation - not to pick on you but I have been seeing that comment for 40+ years.

@dickinsonre haha, I guess I was feeling particularly ambitious when I drafted this ticket.

[bemcdonnell]

@aerispaha, I think we can easily restructure the docs based on #174 . Here is a proposal:

 |-- Welcome Page!
 |-- Simple Tutorial (Quick Start)
 |   |---- Installing
 |   |---- Walk User Through Simple INP Read|Edit|Save
 |   |---- Walk User Through Simple RPT Read
 |   |---- Walk User Through Simple Plotting:
 |   |   |---- Map (flooding | pipes)
 |   |   |---- Profile Plot
 |-- INP (READ|EDIT|SAVE) in detail
 |-- RPT (READ) in detail
 |-- OUT (READ) in detail (if added)
 |-- TOOLS
 |   |---- Mapping Plotters
 |   |---- Profile Plotters
 |   |---- Network Analysis
 |   |---- Flooding tools currently onboard

@dickinsonre, HAHAHA! Story of my life

[dickinsonre]

here is the comment in the SWMM3 manual in 1981 - so having too much output as always been an issue

Statistics Block --

Output from continuous simulation can be enormous if results for every time step are printed. Even the monthly and annual summaries contain more information than may easily be assimilated. The Statistics Block has the capability to review the time step output from a continuous (or single event) simulation, separate output into discrete storm events, rank the events according to almost any desired criterion (e.g., peak or average runoff rate, pollutant load, etc.), assign empirical frequencies and return periods to runoff and pollutant parameters, tabulate and graph the results, and calculate statistical moments. Output from this block can thus be used to identify key events for further study and for many other screening and analytical purposes.