generate documentation automatically with Sphinx (#141)

* remove submodule as it no longer exists

* first draft of Sphinx docs

* copy documentation from ADCIRCpy NOAA tech report

* add figures

* add references to TOC and also turn citations into footnotes

* name abstract

* use `coupledmodelvalidation` for `plot_fort61`

* `:python:` is not a valid directive

* add references to abstract, and fix references page to list all citations

* add docs badge and link to docs

Co-authored-by: zacharyburnett <[email protected]>

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.readthedocs.yml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - documentation

README.md

@@ -8,6 +8,9 @@
 [![version](https://img.shields.io/pypi/v/adcircpy)](https://pypi.org/project/adcircpy)
 [![license](https://img.shields.io/github/license/zacharyburnettNOAA/adcircpy)](https://opensource.org/licenses/gpl-license)
 [![style](https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw)](https://sourceforge.net/p/oitnb/code)
+[![documentation](https://readthedocs.org/projects/adcircpy/badge/?version=latest)](https://adcircpy.readthedocs.io/en/latest/?badge=latest)
+
+Documentation can be found at https://adcircpy.readthedocs.io
 
 ### Installation notes:
 

adcircpy/cmd/plot_fort61.py

@@ -3,11 +3,11 @@
 import os
 from pathlib import Path
 
+from coupledmodelvalidation import COOPS
 import matplotlib.pyplot as plt
 import numpy as np
 
 from adcircpy.outputs import Fort61
-from adcircpy.validation import COOPS
 
 
 def parse_args():

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/abstract.rst

@@ -0,0 +1,11 @@
+Abstract
+========
+
+The Advanced Circulation Model (ADCIRC) :footcite:p:`Luettich1992` is a Fortran program used for modeling ocean circulation due to tides, surface waves and atmospheric forcings.
+However, the input formats and configuration are inflexible and not straight forward for operational implementation, making rapid iteration of model testing, ensemble configuration, and model coupling complicated.
+Here, we introduce a flexible abstraction of model inputs and outputs written in Python, called ADCIRCpy :footcite:p:`JaimeCalzadaNOAA2021`, that provides a simpler user interface for automatically generating ADCIRC configuration to a variety of inputs and model scenarios.
+This documentation outlines 1. the needs for such an abstraction, 2. the peculiarities and challenges with the ADCIRC model that necessitate custom logic, and 3. methodologies for generalizing user input in such a way as to make generating model configurations consistent, fast, and efficient.
+
+`Python, ADCIRC, configuration generation, circulation modeling, user interface`
+
+.. footbibliography::

docs/source/acknowledgments.rst

@@ -0,0 +1,4 @@
+Acknowledgments
+===============
+
+The authors would like to express his acknowledgment to Dr. Joannes Westerink for motivating this work, and to all the ADCIRC developers who have worked to make the ADCIRC software possible.

docs/source/basic_usage.rst

@@ -0,0 +1,89 @@
+Basic Usage
+===========
+
+`Example 1`_ (below) illustrates usage of the ADCIRCpy Python API to generate a "best track" parametric wind configuration for running ADCIRC on hurricane Sandy (2012).
+
+.. _Example 1:
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+
+    from datetime import timedelta
+
+    from adcircpy import AdcircMesh, AdcircRun, Tides
+    from adcircpy.forcing.winds import BestTrackForcing
+    from adcircpy.server import SlurmConfig
+
+    # load an ADCIRC mesh grid from a `fort.14` file to a new mesh object
+    mesh = AdcircMesh.open('fort.14', crs='epsg:4326')
+
+    # add nodal attributes from a `fort.13` file to the mesh object
+    mesh.import_nodal_attributes('fort.13')
+
+    # create a tidal forcing object, using all constituents
+    tidal_forcing = Tides()
+    tidal_forcing.use_all()
+
+    # add data from the tidal forcing object to the mesh object
+    mesh.add_forcing(tidal_forcing)
+
+    # create a wind forcing object for Hurricane Sandy (2012)
+    wind_forcing = BestTrackForcing('Sandy2012')
+
+    # add wind forcing data to the mesh object
+    mesh.add_forcing(wind_forcing)
+
+    # create a Slurm (HPC job manager) configuration object.
+    slurm = SlurmConfig(
+        account='account',
+        ntasks=1000,
+        run_name='ADCIRCpy documentation example',
+        partition='partition',
+        walltime=timedelta(hours=8),
+        mail_type='all',
+        mail_user='[email protected]',
+        log_filename='example.log',
+        modules=['intel/2020', 'impi/2020', 'netcdf/4.7.2-parallel'],
+        path_prefix='$HOME/adcirc/build',
+    )
+
+    # create an ADCIRC run driver object
+    driver = AdcircRun(
+        mesh=mesh,
+        server_config=slurm,
+        spinup_time=timedelta(days=15),
+    )
+
+    # write configuration files to the specified directory
+    driver.write(output_directory="./model_inputs")
+
+The set of files generated by this configuration (``fort.14``, ``fort.15.coldstart``, ``fort.15.hotstart``, ``fort.22``, and ``slurm.job``) represents the minimum working example for an ADCIRC run using parametric winds. To submit this configuration to the Slurm job manager, run the following command in a shell with access to the ADCIRC binaries:
+
+.. code-block:: shell
+
+    sbatch slurm.job
+
+Note that this setup generates model inputs based on default values. These may not be necessarily optimal. For this reason, it is advisable that users perform checks of the outputs and introduce optimizations by modifying the parameters given to the Python API. For example, the user might want to check that the auto-computed timestep matches the expectations from experience. Instead of doing manual modifications to the ``fort.15`` file, the user makes use of the ADCIRCpy module to customize and optimize their modeling needs. If the user, for example, requires their model to use a specific timestep of two seconds, it would suffice to execute the following statement:
+
+.. code-block:: python
+
+    driver.timestep = 2
+
+before :code:`driver.write()`. Most of the ``fort.15`` options can be overridden directly by the user, with a very small exception of parameters that should be considered "private" in the context of the ``fort.15`` file.
+
+.. code-block:: python
+
+    # Modify timestep to 2 seconds.
+    driver.timestep = 2.
+
+    # Add a constant Mannings coefficient field to the mesh
+    mesh.mannings_n_at_sea_floor = mesh.coords.shape[0]*[0.025]
+
+    # generate TAU0 factors
+    mesh.generate_tau0()
+
+    # Write new model configuration to disk.
+    driver.write("model_inputs_modified", overwrite=True)
+
+After these modifications, the resulting directory contains ``fort.13``, ``fort.14``, ``fort.15.coldstart``, ``fort.15.hotstart``, ``fort.22``, and ``slurm.job``. The new ``fort.13`` includes the newly-added Manning's N and :code:`TAU0` factors.

docs/source/cli.rst

@@ -0,0 +1,106 @@
+CLI Commands
+============
+
+The :code:`adcircpy` command line interface (CLI) provides commands accessible from the command line, allowing a smart way to produce forecasts, tidal-only hindcasts, "best track" hindcast operations, and practicing parametric winds appropriate for storm surge hindcasts, for rapid iteration and debugging. A single command generates a sanitized file through Python code, which is user-customized to the virtual model scenario.
+
+``tide_gen``
+------------
+The :code:`tide_gen` command generates the tidal forcing table required in the ``fort.15`` file. The generated table is suitable for being pasted onto a target ``fort.15`` file. In reality, this algorithm calls the same functions invoked when generating full model runs, so it can be used to check whether the tidal forcing outputs will look reasonable before running the entirety of the algorithm.
+
+.. code-block:: shell
+
+    tide_gen /path/to/your/fort.14 '2021-02-26T00:00:00' 15 --mesh-crs='epsg:4326'
+
+.. program-output:: tide_gen -h
+
+``tidal_run``
+-------------
+The :code:`tidal_run` entrypoint will generate the necessary set of input files for forecast and hindcast tidal-only runs with any mesh. Most of the options that tidal_run takes are also valid for other command line entry points, so getting familiar with the options on tidal_run is helpful to understand the options for more advanced CLI entry points. A tidal only run is perhaps the first step towards mesh validation, and mesh stability checks, therefore having an entrypoint that is able to generate ADCIRC input files for tidal only runs pays greatly for initial mesh stability checks.
+
+.. code-block:: shell
+
+    tidal_run \
+        /path/to/fort.14 \
+        $(date +"%Y-%m-%dT%H:%M:%S") \
+        15 \
+        --spinup-days=5  \
+        --tau0-gen  \
+        --crs=EPSG:4326  \
+        --constituents=all \
+        --timestep=10. \
+        --stations-file=stations.txt \
+        --elev-stat=6. \
+        --generate-linear-mannings
+
+.. program-output:: tidal_run -h
+
+``best_track_run``
+------------------
+The :code:`best_track_run` command line entry point was designed to be able to generate a full parametric wind run in ADCIRC from the command line. This entry point essentially encapsulates most of the :code:`adcircpy` functionality in a single command. The following is an example of how to invoke this functionality from the bash shell.
+
+.. code-block:: shell
+
+    best_track_run \
+        fort.14 \
+        Ike2008 \
+        --spinup-days=15 \
+        --crs=EPSG:4326 \
+        --fort13=fort.13 \
+        --output-directory=Ike2008 \
+        --constituents=major \
+        --skip-run \
+        --generate-linear-mannings \
+        --tau0-gen \
+        --timestep=1.0 \
+        --elev=60. \
+        --stations-file=coops.txt \
+        --elev-stat=6. \
+        --binaries-prefix=.python_env/bin \
+        --overwrite \
+        --use-slurm \
+        --account=nosofs \
+        --slurm-ntasks=800 \
+        --partition=orion \
+        --walltime=8 \
+        --mail-type=all \
+        [email protected] \
+        --module=intel/2020 \
+        --module=impi/2020 \
+        --module=netcdf/4.7.2-parallel \
+        --log-level=info
+
+.. program-output:: best_track_run -h
+
+``best_track_file``
+-------------------
+The :code:`best_track_file` entry point generates an ``aswip``-ready "best track" file. This uses the :code:`adcircpy.forcing.winds.BestTrackForcing` class.
+
+.. code-block:: shell
+
+    best_track_file Sandy2012
+
+.. program-output:: best_track_file -h
+
+``fort63``
+----------
+.. program-output:: fort63 -h
+
+``plot_maxele``
+---------------
+.. program-output:: plot_maxele -h
+
+``plot_fort61``
+---------------
+.. code-block:: shell
+
+    plot_fort61 /path/to/fort.61.nc MSL --show --coops-only
+
+.. program-output:: plot_fort61 -h
+
+``plot_mesh``
+-------------
+.. code-block:: shell
+
+    plot_mesh /path/to/fort.14 --show-elements
+
+.. program-output:: plot_mesh -h