Merge pull request #4 from adcroft/docs

Docs

.github/workflows/documentation-and-style.yml

@@ -0,0 +1,26 @@
+name: Doxygen completeness
+
+on: [push, pull_request]
+
+jobs:
+  doxygen:
+
+    runs-on: ubuntu-20.04
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install packages used when generating documentation
+      run: |
+        sudo apt-get update
+        sudo apt-get install doxygen graphviz
+
+    - name: Build doxygen HTML
+      run: |
+        cd docs
+        doxygen
+
+    - name: Report doxygen errors
+      run: |
+        cat docs/doxygen.log
+        test ! -s docs/doxygen.log

README.md

@@ -1,18 +1,19 @@
-Disclaimer
-==========
+# KID (icebergs)
 
-The United States Department of Commerce (DOC) GitHub project code is provided
-on an "as is" basis and the user assumes responsibility for its use. DOC has
-relinquished control of the information and no longer has responsibility to
-protect the integrity, confidentiality, or availability of the information. Any
-claims against the Department of Commerce stemming from the use of its GitHub
-project will be governed by all applicable Federal law. Any reference to
-specific commercial products, processes, or services by service mark,
-trademark, manufacturer, or otherwise, does not constitute or imply their
-endorsement, recommendation or favoring by the Department of Commerce. The
-Department of Commerce seal and logo, or the seal and logo of a DOC bureau,
-shall not be used in any manner to imply endorsement of any commercial product
-or activity by DOC or the United States Government.
+[![Documentation Status](https://readthedocs.org/projects/kid/badge/?version=latest)](https://kid.readthedocs.io/en/latest/?badge=latest)
 
-This project code is made available through GitHub but is managed by NOAA-GFDL
-at https://gitlab.gfdl.noaa.gov.
+# What files are what
+
+| File/directory    | Purpose |
+| --------------    | ------- |
+| src/              | Source code for icebergs |
+| driver/           | A driver for creating a stand-alone (uncoupled to ocean/atmosphere) model |
+| build/            | A workspace for building a stand alone executable using src/ and driver/ |
+| tests/            | Test cases |
+| docs/             | A workspace for generating documentation with doxygen and sphinx |
+
+# Disclaimer
+
+The United States Department of Commerce (DOC) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. DOC has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any claims against the Department of Commerce stemming from the use of its GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.
+
+This project code is made available through GitHub but is managed by NOAA-GFDL at https://gitlab.gfdl.noaa.gov.

docs/.gitignore

@@ -1,2 +1,3 @@
+_build
 html 
 doxygen.log

docs/Doxyfile

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "icebergs"
+PROJECT_NAME           = "KID (icebergs)"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -780,7 +780,7 @@ WARN_LOGFILE           = doxygen.log
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../
+INPUT                  = ../src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -948,7 +948,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ../README.md
+USE_MDFILE_AS_MAINPAGE = ../src/README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

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     = .
+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/README.md

@@ -0,0 +1,13 @@
+Building the documentation
+==========================
+
+Using just doxygen
+```
+doxygen
+```
+will create HTML in the directory `html/`. Error messages will appear in `doxygen.log`.
+
+The readthedocs site, https://kid.readthedocs.io/, is generated using sphinx (see https://sphinx-doc.org/, install with `conda install sphinx`) with
+```
+make html
+```

docs/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import subprocess
+subprocess.call('doxygen', shell=True)
+
+# -- Project information -----------------------------------------------------
+
+project = 'KID (icebergs)'
+copyright = '2021, Adcroft, Huth, Martin, Stern'
+author = 'Adcroft, Huth, Martin, Stern'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+#templates_path = ['_templates']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'ls'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+html_extra_path = ['html']

docs/index.rst

@@ -0,0 +1,15 @@
+.. KID documentation master file, created by
+   sphinx-quickstart on Tue Jan 12 14:38:30 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to KID's documentation!
+===============================
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

src/README.md

@@ -0,0 +1,13 @@
+# Krazy Icebergs Dude (KID)
+
+KID is a Lagrangian element model of icebergs. Initially, the icebergs were represented as infinitesimal points (Martin & Adcroft, 2010), and then given finite extent and element-element interactions so that can now represent giant tabular icebergs by joining elements togeter (Stern et al., 2017).
+
+It should be noted that the K and D in KID can be anything you like, e.g. Kinematic and Dynamics. Suggestions are welcome, since we haven't thought of anything that makes sense.
+
+
+## Publications about KID
+
+- Stern, A. A., A. Adcroft, and O. Sergienko, 2019: Modeling Ice Shelf Cavities and Tabular Icebergs Using Lagrangian Elements. Journal Geophysical Research: Oceans, 124, 3378–3392, https://doi.org/10.1029/2018JC014876.
+- Stern, A. A., A. Adcroft, O. Sergienko, and G. Marques, 2017: Modeling tabular icebergs submerged in the ocean. Journal for Advances in Modeling Earth Systems, 9, 1948–1972, https://doi.org/10.1002/2017MS001002.
+- Stern, A. A., A. Adcroft, and O. Sergienko, 2016: The effects of Antarctic iceberg calving-size distribution in a global climate model. Journal of Geophysical Research: Oceans, 121, 5773–5788, https://doi.org/10.1002/2016JC011835.
+- Martin, T., and A. Adcroft, 2010: Parameterizing the fresh-water flux from land ice to ocean with interactive icebergs in a coupled climate model. Ocean Modelling, 34, 111–124, https://doi.org/10.1016/j.ocemod.2010.05.001.

src/icebergs.F90

@@ -3705,7 +3705,7 @@ end subroutine rotate
 subroutine calculate_mass_on_ocean(bergs, with_diagnostics)
   ! Arguments
   type(icebergs), pointer :: bergs !< Container for all types and memory
-  logical, intent(in) :: with_diagnostics
+  logical, intent(in) :: with_diagnostics !< If true, calculate diagnostics
   ! Local variables
   type(iceberg), pointer :: berg
   type(icebergs_gridded), pointer :: grd
@@ -3800,8 +3800,8 @@ subroutine icebergs_run(bergs, time, calving, uo, vo, ui, vi, tauxa, tauya, ssh,
   real, dimension(:,:), intent(in) :: sst !< Sea-surface temperature (C or K)
   real, dimension(:,:), intent(in) :: cn !< Sea-ice concentration (nondim)
   real, dimension(:,:), intent(in) :: hi !< Sea-ice thickness (m)
-  integer, optional, intent(in) :: stagger
-  integer, optional, intent(in) :: stress_stagger
+  integer, optional, intent(in) :: stagger !< Enumerated value indicating staggering of ocean/ice u,v variables
+  integer, optional, intent(in) :: stress_stagger !< Enumerated value indicating staggering of stress variables
   real, dimension(:,:), optional, intent(in) :: sss !< Sea-surface salinity (1e-3)
   real, dimension(:,:), optional, pointer :: mass_berg !< Mass of bergs (kg)
   real, dimension(:,:), optional, pointer :: ustar_berg !< Friction velocity on base of bergs (m/s)
@@ -5758,11 +5758,20 @@ subroutine evolve_icebergs_mts2(bergs)
 end subroutine evolve_icebergs_mts2
 
 !> Energy calculations for MTS_part==1
-subroutine mts_energy_part_1(bergs,berg,ax1,ay1,axn,ayn,bxn,byn,Fec_x,Fec_y,Fdc_x,Fdc_y)
+subroutine mts_energy_part_1(bergs, berg, ax1, ay1, axn, ayn, bxn, byn, Fec_x, Fec_y, Fdc_x, Fdc_y)
   ! Arguments
   type(icebergs), pointer :: bergs !< Container for all types and memory
-  type(iceberg), pointer :: berg
-  real, intent(in) :: ax1,ay1,axn,ayn,bxn,byn,Fec_x,Fec_y,Fdc_x,Fdc_y
+  type(iceberg), pointer :: berg !< Berg for which to do calculations
+  real, intent(in) :: ax1 !< x acceleration at beginning of step [m s-2] ???
+  real, intent(in) :: ay1 !< y acceleration at beginning of step [m s-2] ???
+  real, intent(in) :: axn !< x acceleration at end of step [m s-2] ???
+  real, intent(in) :: ayn !< y acceleration at end of step [m s-2] ???
+  real, intent(in) :: bxn !< x implicit acceleration [m s-2] ???
+  real, intent(in) :: byn !< y implicit acceleration [m s-2] ???
+  real, intent(in) :: Fec_x !< x component of some force [units ?] ???
+  real, intent(in) :: Fec_y !< y component of some force [units ?] ???
+  real, intent(in) :: Fdc_x !< x component of some other force [units ?] ???
+  real, intent(in) :: Fdc_y !< y component of some other force [units ?] ???
   ! Local
   real :: dt, M, Fex, Fey, Fex_i, Fey_i
   real :: uveln, vveln, uveln_star, vveln_star, ustar, vstar
@@ -5858,9 +5867,10 @@ end subroutine mts_energy_part_1
 subroutine mts_energy_part_3(bergs,berg,uvel3,vvel3,whichtime)
   ! Arguments
   type(icebergs), pointer :: bergs !< Container for all types and memory
-  type(iceberg), pointer :: berg
-  real,intent(in) :: uvel3,vvel3
-  integer,intent(in) :: whichtime
+  type(iceberg), pointer :: berg !< Berg to do calculations for
+  real,intent(in) :: uvel3 !< u-component of velocity [m s-1]  but why 3???
+  real,intent(in) :: vvel3 !< v-component of velocity [m s-1]  but why 3???
+  integer,intent(in) :: whichtime !< Time level ???
   ! Local
   real :: dt, M, Fex, Fey, Fdx, Fdy