Merge pull request #42 from amoodie/docs

improve documentation in main loops

.travis.yml

@@ -26,12 +26,11 @@ jobs:
       python: "3.8"
       install: 
         - pip install -r requirements.txt
-        - pip install -e .
-        - pip install sphinx sphinx-automodapi
+        - pip install -r requirements-docs.txt
         - sudo apt update -y && sudo apt install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended dvipng
+        - pip install -e .
       script:
-        - (cd docs && sphinx-build -E -W -b linkcheck source build) 
-        - (cd docs && make html)
+        - (cd docs && make docs)
       deploy:
         provider: pages:git
         github_token: $GITHUB_TOKEN

docs/source/conf.py

@@ -51,7 +51,7 @@
 # Napoleon settings
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = False
+napoleon_include_init_with_doc = True
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = True
 napoleon_use_admonition_for_examples = False

docs/source/guides/userguide.rst

@@ -5,10 +5,11 @@ User Guide
 Guide to users!
 
 
-Configuring the input yaml file
-===============================
+==============================
+Configuring an input YAML file
+==============================
 
-The configuration for a pyDeltaRCM run is set up by a parameter set, described in the ``yaml`` markup format.
+The configuration for a pyDeltaRCM run is set up by a parameter set, described in the ``YAML`` markup format.
 To configure a run, you should create a file called, for example, ``run_parameters.yml``. 
 Inside this file you can specify parameters for your run, with each parameter on a new line. For example, if ``run_parameters.yml`` contained the line: 
 
@@ -19,9 +20,80 @@ Inside this file you can specify parameters for your run, with each parameter on
 then a :obj:`~pyDeltaRCM.deltaRCM_driver.pyDeltaRCM` model instance initialized with this file specified as ``input_file`` will have a slope of 0.005.
 Multiple parameters can be specified line by line.
 
-Default values are substituted for any parameter not explicitly given in the ``input_file`` ``.yaml`` file.
-Default values are defined as:
+Default values are substituted for any parameter not explicitly given in the ``input_file`` ``.yml`` file.
+Default values of the YAML configuration are listed in the :doc:`../reference/deltaRCM_driver/yaml_defaults`.
 
-.. literalinclude:: ../../../pyDeltaRCM/default.yml
-   :language: yaml
-   :linenos: 
+
+===================
+Starting model runs
+===================
+
+There are three ways to interact with the pyDeltaRCM model. 
+Two methods are part of the "high-level" model API, and these approaches each consist of a single line of code.
+The third method is to create a model instance via the "low-level" model API and manually handle timestepping and model finalization.
+
+
+High-level model API
+====================
+
+The high-level API is accessed via either a shell prompt or python script, and is invoked directly if a YAML configuration file includes the ``timesteps`` variable.
+
+.. note::
+    To use the high-level API, the configuration YAML file must contain the ``timesteps`` variable.
+
+Bash API
+--------
+
+For example, to invoke a model run from the bash prompt using the YAML file ``model_configuration.yml`` which looks like:
+
+.. code-block:: yaml
+
+    timesteps: 500
+
+we would simply invoke at the bash prompt:
+
+.. code:: bash
+    
+    python -m pyDeltaRCM --config model_configuration.yml
+
+or equivalently:
+
+.. code:: bash
+    
+    run_pyDeltaRCM --config model_configuration.yml
+
+These invokations will run the pyDeltaRCM with the parameters specified in the ``model_configuration.yml`` file, and automatically :obj:`~pyDeltaRCM.deltaRCM_driver.pyDeltaRCM.update` the model 500 times.
+
+
+Python API
+----------
+
+Alternatively, calling the ``run_model`` method from a python script, with the :meth:`input file <pyDeltaRCM.deltaRCM_driver.pyDeltaRCM.__init__>` parameter specified as the same ``model_configuration.yml`` file above, would run the pyDeltaRCM model, and automatically :obj:`~pyDeltaRCM.deltaRCM_driver.pyDeltaRCM.update` the model 500 times.
+
+
+
+Low-level model API
+===================
+
+iinteract with the model by creating your own script, and manipulating model outputs at the desired level. The simplest case is to do
+
+.. code::
+
+    delta = pyDeltaRCM(input_file='model_configuration.yml')
+
+    for time in range(0,1):
+        delta.update()
+
+    delta.finalize()
+
+However, you can also inspect/modify the :obj:`~pyDeltaRCM.deltaRCM_driver.pyDeltaRCM.update` method, and change the order or add operations as desired.
+
+
+=============================
+Advanced model configurations
+=============================
+
+Configuring multiple model runs from a single YAML file
+==============================================================
+
+todo

docs/source/reference/deltaRCM_driver/index.rst

@@ -12,6 +12,15 @@ This class is defined in ``pyDeltaRCM.deltaRCM_driver``.
 .. currentmodule:: pyDeltaRCM.deltaRCM_driver
 
 .. autosummary:: 
-	:toctree: ../../_autosummary
+    :toctree: ../../_autosummary
 
 	pyDeltaRCM
+
+
+Model configuration reference
+=============================
+
+.. toctree::
+    :maxdepth: 1
+
+    yaml_defaults

docs/source/reference/deltaRCM_driver/yaml_defaults.rst

@@ -0,0 +1,8 @@
+Defaul Model Variable Values
+============================
+
+Default model values are defined as:
+
+.. literalinclude:: ../../../../pyDeltaRCM/default.yml
+   :language: yaml
+   :linenos: 

pyDeltaRCM/deltaRCM_driver.py

@@ -7,6 +7,26 @@
 
 
 class pyDeltaRCM(Tools):
+    """Main pyDeltaRCM model class.
+
+    This is the main model class defined by the package. Instantiating the
+    model class is described in the :meth:`__init__` method below in detail,
+    but generally model instantiation occurs via a model run YAML
+    configuration file. These YAML configuration files define model parameters
+    which are used in the run; read more about creating input YAML
+    configuration files in the :doc:`../../guides/userguide`.
+
+    Once the model has been instantiated, the model is updated via the
+    :meth:`update`. This method coordinates the hydrology, sediment transport,
+    subsidence, and stratigraphic operation that must occur during each
+    timestep. The :meth:`update` should be called iteratively, to "run" the
+    model.
+
+    Finally, after all ``update`` steps are complete, the model should be
+    finalized (:meth:`finalize`), such that files and data are appropriately
+    closed and written to disk.
+
+    """
 
     def __init__(self, input_file=None):
         """Creates an instance of the pyDeltaRCM model.
@@ -19,6 +39,9 @@ def __init__(self, input_file=None):
         input_file : `str`, `os.PathLike`, optional
             User model run configuration file.
 
+        Returns
+        -------
+
         Notes
         -----
         For more information regarding input configuration files, see the
@@ -46,9 +69,27 @@ def __init__(self, input_file=None):
         self.init_output_grids()
 
     def update(self):
+        """Run the model for one full instance
+
+        Calls, in sequence:
+
+            * the routine to run one timestep (i.e., water surface estimation
+              and sediment routing, :meth:`run_one_timestep`)
+            * the basin subsidence update pattern (:meth:`apply_subsidence`)
+            * the timestep finalization routine (:meth:`finalize_timestep`)
+            * straigraphy updating routine (:meth:`record_stratigraphy`)
+
+        If you attempt to override the ``update`` routine, you must implement
+        these operations at a minimum.
+
+        Parameters
+        ----------
+
+        Returns
+        -------
+
         """
-        Run the model for one full instance
-        """
+
         self.run_one_timestep()
 
         self.apply_subsidence()
@@ -61,6 +102,18 @@ def update(self):
         self._time += self.time_step
 
     def finalize(self):
+        """Finalize the model run.
+
+        Finalization includes saving output stratigraphy, closing relevant
+        files on disk and clearing variables.
+
+        Parameters
+        ----------
+
+        Returns
+        -------
+
+        """
 
         self.output_strata()
 
@@ -73,11 +126,16 @@ def finalize(self):
 
         self._is_finalized = True
 
-    # define properties
-
     @property
     def time_step(self):
-        """The time step."""
+        """The time step.
+
+        Raises
+        ------
+        UserWarning
+            If a very small timestep is configured.
+        """
+
         return self._time_step
 
     @time_step.setter