refactoring docs organization

docs/conf.py

@@ -46,6 +46,7 @@
  'sphinx.ext.coverage',
  'sphinx.ext.mathjax',
  'sphinx.ext.viewcode',
+ 'sphinx.ext.autosummary',
  'myst_parser',
 ]
 

docs/index.rst

@@ -1,5 +1,20 @@
-.. include:: ../README.md
- :parser: myst_parser.sphinx_
+swmmio
+========================
+
+.. image:: _static/img/impact_of_option.png
+ :alt: Impact of Option
+
+
+`swmmio` provides a Pythonic interface to the EPA Stormwater Management Model (SWMM)
+allowing engineers to programmatically create, modify, and
+analyze SWMM models.
+
+With `swmmio`, model parameters encoded in the `.inp` file can be
+retrieved conveniently as Pandas dataframes making it possible to make
+automate your hydraulics and hydologic modeling workflow. After simulations are
+completed, results in the `.rpt` file can also be retrieved as Pandas dataframes,
+making post-processing automation trivial.
+
 
 
 .. swmmio documentation master file, created by
@@ -11,11 +26,10 @@
  :maxdepth: 2
  :caption: Contents:
 
- swmmio
- elements
- version_control
- utils
- graphics
+ reference/index
+ installing
+ usage
+
 
 Indices and tables
 ==================

docs/installing.md

@@ -0,0 +1,8 @@
+### Installation
+Before installation, it's recommended to first activate a [virtualenv](https://github.com/pypa/virtualenv) to 
+not crowd your system's package library. If you don't use any of the dependencies listed above, 
+this step is less important. `swmmio` can be installed via pip in your command line:
+
+```console
+pip install swmmio
+```

docs/swmmio.rst → docs/reference/core.rst

@@ -1,4 +1,4 @@
-`swmmio` Core Objects
+`swmmio` core objects
 ========================
 
 .. automodule:: swmmio.core

docs/reference/index.rst

@@ -0,0 +1,20 @@
+.. -*- coding: utf-8 -*-
+
+Reference
+*********
+.. only:: html
+
+ :Release: |release|
+ :Date: |today|
+
+
+.. toctree::
+ :maxdepth: 2
+
+ core
+ elements
+ utils
+ graphics
+ version_control
+
+.. only:: html

docs/usage.md

@@ -0,0 +1,153 @@
+# Usage
+The `swmmio.Model()` class provides the basic endpoint for interfacing with SWMM models. To get started, save a SWMM5 
+model (.inp) in a directory with its report file (.rpt). A few examples: 
+
+```python
+import swmmio
+
+# instantiate a swmmio model object
+mymodel = swmmio.Model('/path/to/directory with swmm files')
+
+# dataframe with useful data related to model nodes, conduits, and subcatchments
+nodes = mymodel.nodes.dataframe
+links = mymodel.links.dataframe
+subs = mymodel.subcatchments.dataframe
+
+# enjoy all the Pandas functions
+nodes.head()
+
+# write to a csv
+nodes.to_csv('/path/mynodes.csv')
+
+# calculate average and weighted average impervious
+avg_imperviousness = subs.PercImperv.mean()
+weighted_avg_imp = (subs.Area * subs.PercImperv).sum() / len(subs)
+```
+
+# Nodes and Links Objects 
+Specific sections of data from the inp and rpt can be extracted with `Nodes` and `Links` objects. 
+Although these are the same object-type of the `swmmio.Model.nodes` and `swmmio.Model.links`, 
+accessing them directly allows for custom control over what sections of data are retrieved. 
+
+```python
+from swmmio import Model, Nodes
+m = Model("coolest-model.inp")
+
+# pass custom init arguments into the Nodes object instead of using default settings referenced by m.nodes() 
+nodes = Nodes(
+ model=m, 
+ inp_sections=['junctions', 'storages', 'outfalls'],
+ rpt_sections=['Node Depth Summary', 'Node Inflow Summary'],
+ columns=[ 'InvertElev', 'MaxDepth', 'InitDepth', 'SurchargeDepth', 'MaxTotalInflow', 'coords']
+)
+
+# access data 
+nodes.dataframe 
+```
+
+# Generating Graphics
+Create an image (.png) visualization of the model. By default, pipe stress and node flood duration is 
+visualized if your model includes output data (a .rpt file should accompany the .inp).
+
+```python
+swmmio.draw_model(mymodel)
+```
+
+![Default Draw Output](_static/img/default_draw.png "Sewer Stress, Node Flooding")
+
+Use pandas to calculate some interesting stats, and generate a image to highlight
+what's interesting or important for your project:
+
+```python
+#isolate nodes that have flooded for more than 30 minutes
+flooded_series = nodes.loc[nodes.HoursFlooded>0.5, 'TotalFloodVol']
+flood_vol = sum(flooded_series) #total flood volume (million gallons)
+flooded_count = len(flooded_series) #count of flooded nodes
+
+#highlight these nodes in a graphic
+nodes['draw_color'] = '#787882' #grey, default node color
+nodes.loc[nodes.HoursFlooded>0.5, 'draw_color'] = '#751167' #purple, flooded nodes
+
+#set the radius of flooded nodes as a function of HoursFlooded
+nodes.loc[nodes.HoursFlooded>1, 'draw_size'] = nodes.loc[nodes.HoursFlooded>1, 'HoursFlooded'] * 12
+
+#make the conduits grey, sized as function of their geometry
+conds['draw_color'] = '#787882'
+conds['draw_size'] = conds.Geom1
+
+#add an informative annotation, and draw:
+annotation = 'Flooded Volume: {}MG\nFlooded Nodes:{}'.format(round(flood_vol), flooded_count)
+swmmio.draw_model(mymodel, annotation=annotation, file_path='flooded_anno_example.png')
+```
+![Flooded highlight](_static/img/flooded_anno_example.png "Node Flooding with annotation")
+
+# Building Variations of Models
+Starting with a base SWMM model, other models can be created by inserting altered data into a new inp file. Useful for sensitivity analysis or varying boundary conditions, models can be created using a fairly simple loop, leveraging the `modify_model` package.
+
+For example, climate change impacts can be investigated by creating a set of models with varying outfall Fixed Stage elevations:
+
+```python
+import os
+import swmmio
+
+# initialize a baseline model object
+baseline = swmmio.Model(r'path\to\baseline.inp')
+rise = 0.0 #set the starting sea level rise condition
+
+# create models up to 5ft of sea level rise.
+while rise <= 5:
+
+ # create a dataframe of the model's outfalls
+ outfalls = baseline.inp.outfalls
+
+ # create the Pandas logic to access the StageOrTimeseries column of FIXED outfalls
+ slice_condition = outfalls.OutfallType == 'FIXED', 'StageOrTimeseries'
+
+ # add the current rise to the outfalls' stage elevation
+ outfalls.loc[slice_condition] = pd.to_numeric(outfalls.loc[slice_condition]) + rise
+ baseline.inp.outfalls = outfalls
+
+ # copy the base model into a new directory 
+ newdir = os.path.join(baseline.inp.dir, str(rise))
+ os.mkdir(newdir)
+ newfilepath = os.path.join(newdir, baseline.inp.name + "_" + str(rise) + '_SLR.inp')
+
+ # Overwrite the OUTFALLS section of the new model with the adjusted data
+ baseline.inp.save(newfilepath)
+
+ # increase sea level rise for the next loop
+ rise += 0.25
+
+```
+
+# Access Model Network
+The `swmmio.Model` class returns a Networkx MultiDiGraph representation of the model via that `network` parameter:
+```python
+
+# access the model as a Networkx MutliDiGraph
+G = model.network
+
+# iterate through links
+for u, v, key, data in model.network.edges(data=True, keys=True):
+
+ print (key, data['Geom1'])
+ # do stuff with the network
+``` 
+
+# Running Models
+Using the command line tool, individual SWMM5 models can be run by invoking the swmmio module in your shell as such:
+```shell
+python -m swmmio --run path/to/mymodel.inp
+```
+If you have many models to run and would like to take advantage of your machine's cores, you can start a pool of simulations with the `--start_pool` (or `-sp`) command. After pointing `-sp` to one or more directories, swmmio will search for SWMM .inp files and add all them to a multiprocessing pool. By default, `-sp` leaves 4 of your machine's cores unused. This can be changed via the `-cores_left` argument.
+```shell
+# run all models in models in directories Model_Dir1 Model_Dir2
+python -m swmmio -sp Model_Dir1 Model_Dir2 
+
+# leave 1 core unused
+python -m swmmio -sp Model_Dir1 Model_Dir2 -cores_left=1
+```
+<div class="warning">
+ <p class="first admonition-title">Warning</p>
+ <p class="last">Using all cores for simultaneous model runs can put your machine's CPU usage at 100% for extended periods of time. This probably puts stress on your hardware. Use at your own risk.</p>
+</div>