Merge pull request USDA-ARS-NWRC#162 from scotthavens/doc_update

Documentation update

.bumpversion.cfg

@@ -7,12 +7,6 @@ tag = True
 
 [bumpversion:file:setup.py]
 
-[bumpversion:file:AUTHORS.rst]
-
-[bumpversion:file:docs/AUTHORS.rst]
-
-[bumpversion:file:docs/CONTRIBUTING.rst]
-
 [bumpversion:file:smrf/__init__.py]
 
 [bumpversion:file:docs/conf.py]

.readthedocs.yml

@@ -0,0 +1,28 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.6
+  install:
+    - requirements: requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

.zenodo.json

@@ -1,5 +1,4 @@
 {
-
     "license": "other-open",
     "title": "Spatial Modeling for Resources Framework (SMRF)",
     "version": "v0.9.1",
@@ -13,41 +12,43 @@
         {
             "affiliation": "USDA Agricultural Research Service",
             "name": "Scott Havens",
-			"orcid": "0000-0002-6933-4485"
+            "orcid": "0000-0002-6933-4485"
         },
         {
             "affiliation": "USDA Agricultural Research Service",
             "name": "Danny Marks",
-			"orcid": "0000-0003-3105-8427"
+            "orcid": "0000-0003-3105-8427"
         },
         {
             "affiliation": "National Weather Service River Forecast Center",
             "name": "Patrick Kormos",
-			"orcid": "0000-0003-1874-9215"
+            "orcid": "0000-0003-1874-9215"
         },
         {
             "affiliation": "USDA Agricultural Research Service",
             "name": "Andrew Hedrick",
-      "orcid": "0000-0001-9511-1341"
+            "orcid": "0000-0001-9511-1341"
+        },
+        {
+            "affiliation": "Sierra Nevada Research Institute, University of California and USDA Agricultural Research Service",
+            "name": "Ernesto Trujillo",
+            "orcid": "0000-0001-9731-7482"
         },
         {
             "affiliation": "USDA Agricultural Research Service",
             "name": "Micah Johnson",
-			"orcid": "0000-0003-4029-8545"
+            "orcid": "0000-0003-4029-8545"
         },
         {
             "affiliation": "USDA Agricultural Research Service",
             "name": "Micah Sandusky",
-			"orcid": "0000-0002-4235-5876"
+            "orcid": "0000-0002-4235-5876"
         },
         {
             "affiliation": "USDA Agricultural Research Service",
             "name": "Mark Robertson",
-			"orcid": "0000-0003-4621-0161"
+            "orcid": "0000-0003-4621-0161"
         }
-
     ],
-
     "access_right": "open"
-
-}
+}

AUTHORS.md

@@ -0,0 +1,15 @@
+# Authors
+
+## Development Lead
+
+* Scott Havens [@scotthavens](http://github.com/scotthavens)
+
+## Contributors
+
+* Micah Johnson [@micahjohnson150](http://github.com/micahjohnson150)
+* Micah Sandusky [@micah-prime](http://github.com/micah-prime)
+* Mark Robertson [@robertson-mark](http://github.com/robertson-mark)
+* Danny Marks [@dannymarks](http://github.com/dannymarks)
+* Andrew Hedrick  [@Hedrick-ARS](http://github.com/Hedrick-ARS)
+* Joachim Meyer [@jomey](https://github.com/jomey)
+* Ernesto Trujillo [@etujil](https://github.com/etrujil)

Makefile

@@ -9,7 +9,7 @@ except:
 webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
 endef
 export BROWSER_PYSCRIPT
-BROWSER := python -c "$$BROWSER_PYSCRIPT"
+BROWSER := python3 -c "$$BROWSER_PYSCRIPT"
 
 help:
 	@echo "clean - remove all build, test, coverage and Python artifacts"
@@ -66,7 +66,7 @@ coverage:
 docs:
 	rm -f docs/smrf.rst
 	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ smrf
+	sphinx-apidoc -o docs/api smrf
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html

README.md

@@ -8,54 +8,99 @@
 [![Build Status](https://travis-ci.org/USDA-ARS-NWRC/smrf.svg?branch=develop)](https://travis-ci.org/USDA-ARS-NWRC/smrf)
 [![Coverage Status](https://coveralls.io/repos/github/USDA-ARS-NWRC/smrf/badge.svg?branch=HEAD)](https://coveralls.io/github/USDA-ARS-NWRC/smrf?branch=HEAD)
 
-Spatial Modeling for Resources Framework (SMRF) was developed by Dr. Scott
-Havens at the USDA Agricultural Research Service (ARS) in Boise, ID. SMRF was
-designed to increase the flexibility of taking measured weather data and
-distributing the point measurements across a watershed. SMRF was developed to be
-used as an operational or research framework, where ease of use, efficiency,
-and ability to run in near real time are high priorities.
+Spatial Modeling for Resources Framework (SMRF) was developed by Dr. Scott Havens at the USDA Agricultural Research Service (ARS) in Boise, ID. SMRF was designed to increase the flexibility of taking measured weather data and distributing the point measurements across a watershed. SMRF was developed to be used as an operational or research framework, where ease of use, efficiency, and ability to run in near real time are high priorities.
 
-## Usage
-Read the full documentation for [SMRF](https://smrf.readthedocs.io) including
-up to date installation instructions.
+Read the [full documentation for SMRF](https://smrf.readthedocs.io) including up to date installation instructions.
 
+- [Spatial Modeling for Resources Framework](#spatial-modeling-for-resources-framework)
+  - [Installation](#installation)
+  - [Topo setup](#topo-setup)
+  - [Input data](#input-data)
+  - [Running SMRF](#running-smrf)
+  - [Docker](#docker)
 
-## Quick Start
+## Installation
 
-### Native install
+To install SMRF locally on Linux of MacOSX, first clone the repository and build into a virtual environment. This requires `gcc <= 9.0`. The general steps are as follows and will test the SMRF installation by running the tests.
 
-### Docker
+Clone from the repository
 
-To mount a data volume, so that you can share data between the local file
-system and the docker, the `-v` option must be used. For a more in depth
-discussion and tutorial, read
-https://docs.docker.com/engine/userguide/containers/dockervolumes/. The
-container has a shared data volume at `/data` where the container can access
-the local file system.
+```bash
+git clone https://github.com/USDA-ARS-NWRC/smrf.git
+```
+
+And install the requirements, SMRF and run the tests.
+
+```bash
+python3 -m pip install -r requirements_dev.txt
+python3 setup.py install
+```
+
+To optionally verify the installation, run the unit tests
+
+```bash
+python3 -m unittest -v
+```
+
+For Windows, the install method is using [Docker](#Docker).
+
+## Topo setup
+
+The topo provides SMRF with the following static layers:
+
+1. Digital elevation model
+2. Vegetation type
+3. Vegetation height
+4. Vegetation extinction coefficient
+5. Vegetation optical transmissivity
+6. Basin mask (optional)
 
-When the image is ran, it will go into the Python terminal within the image.
-Within this terminal, SMRF can be imported. The command `/bin/bash` can be
-appended to the end of docker run to enter into the docker terminal for full
-control. It will start in the `/data` location with SMRF code in `/code/smrf`.
+All these layers are stored in a netCDF file, typically referred to the `topo.nc` file.
 
-For Linux
-`docker run -v <path>:/data -it usdaarsnwrc/smrf [/bin/bash]`
+While the `topo.nc` file can be generated manually, a great option is to use [basin_setup](https://github.com/USDA-ARS-NWRC/basin_setup) which creates a topo file that is compatible with SMRF and AWSM.
 
-For MacOSX:
-`docker run -v /Users/<path>:/data -it usdaarsnwrc/smrf [/bin/bash]`
+## Input data
 
-For Windows:
-`docker run -v /c/Users/<path>:/data -it usdaarsnwrc/smrf [/bin/bash]`
+Input meterological data for SMRF requires the following variables:
 
+- Air temperature
+- Vapor pressure
+- Precipitation
+- Wind speed and direction
+- Cloud factor (percentage between 0 and 1 of incoming solar obstructed by clouds)
 
-#### Running the test
+The data can be supplied through the following formats:
 
+- CSV files
+- [MySQL database](https://github.com/USDA-ARS-NWRC/weather_database)
+- Weather Research and Forecasting (WRF) outputs
+- High Resolution Rapid Refresh (HRRR)
+- Generic netCDF
+
+## Running SMRF
+
+There are two ways to run SMRF, first is through the `run_smrf` command or through the SMRF API. If SMRF is being used as input to a snow or hydrology model, we recommend to use `run_smrf` as it will generate all the input required. See the full documentation for more details.
+
+```bash
+run_smrf <config_file>
 ```
-docker run -it usdaarsnwrc/smrf /bin/bash
-cd /code/smrf
-gen_maxus --out_maxus test_data/topo/maxus.nc test_data/topo/dem.ipw
-run_smrf.py test_data/testConfig.ini
+
+## Docker
+
+SMRF is also built into a docker image to make it easy to install on any operating system. The docker images are built automatically from the Github repository and include the latest code base or stable release images.
+
+The SMRF docker image has a folder meant to mount data inside the docker image at `/data`.
+
+```bash
+docker run -v <path to data>:/data usdaarsnwrc/smrf run_smrf <path to config>
 ```
 
-The output netCDF files will be placed in the `/code/smrf/test_data/output`
-location.
+The `<path to data>` should be the path to where the configuration file, data and topo are on the host machine. This will also be the location to where the SMRF output will go.
+
+**NOTE:** The paths in the configuration file must be adjusted for being inside the docker image. For example, in the command above the path to the config will be inside the docker image. This would be `/data/config.ini` and not the path on the host machine.
+
+In a way that ARS uses this, we keep the config, topo and data on one location as the files are fairly small. The output then is put in another location as it file size can be much larger. To facilitate this, mount the input and output data separately and modify the configuration paths.
+
+```bash
+docker run -v <input>:/data/input -v <output>:/data/output usdaarsnwrc/smrf run_smrf <path to config>
+```

docs/Makefile

@@ -50,7 +50,7 @@ clean:
 
 .PHONY: html
 html:
-	@cd ../; python setup.py build_ext --inplace
+	@cd ../; python3 setup.py build_ext --inplace
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/api.rst → docs/api/index.rst

@@ -10,8 +10,6 @@ Everything you could ever want to know about SMRF.
    smrf.distribute
    smrf.envphys
    smrf.framework
-   smrf.ipw
-   smrf.model
    smrf.output
    smrf.spatial
    smrf.utils

docs/api/modules.rst

@@ -0,0 +1,7 @@
+smrf
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   smrf

docs/api/smrf.data.rst

@@ -0,0 +1,46 @@
+smrf.data package
+=================
+
+Submodules
+----------
+
+smrf.data.loadData module
+-------------------------
+
+.. automodule:: smrf.data.loadData
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+smrf.data.loadGrid module
+-------------------------
+
+.. automodule:: smrf.data.loadGrid
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+smrf.data.loadTopo module
+-------------------------
+
+.. automodule:: smrf.data.loadTopo
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+smrf.data.mysql\_data module
+----------------------------
+
+.. automodule:: smrf.data.mysql_data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: smrf.data
+   :members:
+   :undoc-members:
+   :show-inheritance: