Merge pull request #87 from jr3cermak/esmg-test

Doxygen support for 1.8.13 through 1.8.20

Author: kshedstrom

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

@@ -18,11 +18,11 @@ jobs:
       continue-on-error: true
 
     - name: Install packages used when generating documentation
-      run: >
-        sudo apt-get install
-        python3-sphinx python3-lxml perl
-        texlive-binaries texlive-base bibtool tex-common texlive-bibtex-extra
-        graphviz
+      run: |
+        sudo apt-get update
+        sudo apt-get install python3-sphinx python3-lxml perl
+        sudo apt-get install texlive-binaries texlive-base bibtool tex-common texlive-bibtex-extra
+        sudo apt-get install graphviz
 
     - name: Build doxygen HTML
       run: |

.github/workflows/regression.yml

@@ -23,5 +23,5 @@ jobs:
     - name: Create validation data
       run: make run.symmetric -k -s
 
-    - name: Regression test 
+    - name: Regression test
       run: make test.regressions DO_REGRESSION_TESTS=true -k -s

.readthedocs.yml

@@ -1,8 +1,9 @@
 version: 2
 
 # Extra formats
-formats:
-  - pdf
+# PDF generation is failing for now; disabled on 2020-12-02
+#formats:
+#  - pdf
 
 # Build documentation
 sphinx:

docs/Doxyfile_nortd

@@ -279,7 +279,7 @@ ALIASES += footnote{1}="\latexonly\footnote\{\1\}\endlatexonly\htmlonly<sup titl
 # what it does and just passes through the string uninterpreted.
 # The image also needs to be added to LATEX_EXTRA_FILES.
 # Default 3rd argument: \includegraphics[width=\textwidth\,height=\textheight/2\,keepaspectratio=true]
-ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\n\3{\1}\n\doxyfigcaption{\2}\n\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
+ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\3{\1}\doxyfigcaption{\2}\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"

docs/Doxyfile_nortd_latex

@@ -279,7 +279,7 @@ ALIASES += footnote{1}="\latexonly\footnote\{\1\}\endlatexonly\htmlonly<sup titl
 # what it does and just passes through the string uninterpreted.
 # The image also needs to be added to LATEX_EXTRA_FILES.
 # Default 3rd argument: \includegraphics[width=\textwidth\,height=\textheight/2\,keepaspectratio=true]
-ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\n\3{\1}\n\doxyfigcaption{\2}\n\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
+ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\3{\1}\doxyfigcaption{\2}\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"

docs/Doxyfile_rtd

@@ -256,7 +256,7 @@ ALIASES += footnote{1}="\latexonly\footnote\{\1\}\endlatexonly\htmlonly<sup titl
 # what it does and just passes through the string uninterpreted.
 # The image also needs to be added to LATEX_EXTRA_FILES.
 # Default 3rd argument: \includegraphics[width=\textwidth\,height=\textheight/2\,keepaspectratio=true]
-ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\n\3{\1}\n\doxyfigcaption{\2}\n\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
+ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\3{\1}\doxyfigcaption{\2}\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"

docs/Doxyfile_rtd_dox

@@ -256,7 +256,7 @@ ALIASES += footnote{1}="\latexonly\footnote\{\1\}\endlatexonly\htmlonly<sup titl
 # what it does and just passes through the string uninterpreted.
 # The image also needs to be added to LATEX_EXTRA_FILES.
 # Default 3rd argument: \includegraphics[width=\textwidth\,height=\textheight/2\,keepaspectratio=true]
-ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\n\3{\1}\n\doxyfigcaption{\2}\n\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
+ALIASES += imagelatex{3}="\latexonly\begin{DoxyImage}\3{\1}\doxyfigcaption{\2}\end{DoxyImage}\endlatexonly\xmlonly<image type=\"latex\" name=\"\1\">\2</image>\endxmlonly"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -814,12 +814,24 @@ INPUT                  = ../src \
                          ../config_src/dynamic_symmetric \
                          ../config_src/external \
                          ../config_src/coupled_driver \
-                         ../src/core/MOM.F90 \
                          ../src/ALE/MOM_ALE.F90 \
+                         ../src/ALE/PCM_functions.F90 \
+                         ../src/core/MOM.F90 \
+                         ../src/core/MOM_density_integrals.F90 \
+                         ../src/diagnostics/MOM_wave_structure.F90 \
                          ../src/equation_of_state/MOM_EOS.F90 \
+                         ../src/framework/MOM_diag_mediator.F90 \
+                         ../src/framework/MOM_domains.F90 \
+                         ../src/framework/MOM_dyn_horgrid.F90 \
+                         ../src/framework/MOM_file_parser.F90 \
                          ../src/framework/MOM_unit_scaling.F90 \
                          ../src/ice_shelf/MOM_ice_shelf.F90 \
-                         ../src/parameterizations/lateral/MOM_MEKE.F90
+                         ../src/parameterizations/lateral/MOM_MEKE.F90 \
+                         ../src/parameterizations/vertical/MOM_bkgnd_mixing.F90 \
+                         ../src/parameterizations/vertical/MOM_energetic_PBL.F90 \
+                         ../src/parameterizations/vertical/MOM_set_viscosity.F90 \
+                         ../src/tracer/oil_tracer.F90 \
+                         ../src/user/user_initialization.F90
 
 # Basic testing units below
 

docs/README.md

@@ -42,6 +42,9 @@ Doxygen in run in two modes.  For the API manual, it is instructed to generate o
 
 If the software is installed, local copies of html and pdf instead of those found at RTD.  The html and pdf versions produced by doxygen will not have any of the additional documentation from the sphinx portion of the pipeline.
 
+RTD by default runs html(sphinx) pipeline and adds a bit of styling.  The RTD can be instructed to also produce a PDF.  However, the current pipeline exceeds 900 seconds
+execution time and fails if RTD is instructed to generate the html and PDF in one session.  By default, the PDF generation is currently turned off.
+
 ## Starting structure
 
 We define `SRC` as the root of the source directory assuming the `$(SRC)` directory was created from downloading the tree from github using `git clone`.
@@ -96,7 +99,7 @@ on the [MOM6 developer's wiki](https://github.com/NOAA-GFDL/MOM6/wiki/Doxygen).
 
 NOTE: Not all doxygen commands are supported through the sphinx documentation processor.  Support can be added by adding an [issue](https://github.com/NOAA-GFDL/MOM6/issues) to the github repository.
 
-For the API documentation, the tree will look like this:
+For the API documentation, the resultant tree will look like this:
 ```
 SRC/
   docs/
@@ -107,7 +110,7 @@ SRC/
     MOM6.tags
 ```
 
-The main driver for doxygen is a configuration file.  The content linked to [MOM6 developer's wiki](https://github.com/NOAA-GFDL/MOM6/wiki/Doxygen) uses the `Doxyfile_nortd` configuration file.
+The main driver for doxygen is a configuration file.  The content on [MOM6 developer's wiki](https://github.com/NOAA-GFDL/MOM6/wiki/Doxygen) uses the `Doxyfile_nortd` configuration file.
 
 By default, the html directory is only available after processing the documentation.  Please see [software operation](software-operation) on how to generate the pdf companion of the documentation.
 
@@ -121,7 +124,7 @@ SRC/
     MOM6.tags
 ```
 
-The documentation generated by Sphinx and RTD uses the `Doxyfile_rtd`.  These options can be overridden at the command line.  See software operation for more details.
+The documentation generated by Sphinx and RTD uses the `Doxyfile_rtd`.  These options can be overridden at the command line.  See [software operation](software-operation) for more details.
 
 The `_build/doxygen_warn_rtd_log.txt` should be reviewed for warnings and errors.
 
@@ -145,7 +148,7 @@ The `html_log.txt` should be reviewed for warnings and errors.
 
 ## Read the Docs
 
-The RTD site can be configured to watch for updates on a github repository.  A documentation update may be triggered when an update is pushed to the repository.  The entire documentation process is run twice.  The first run produces html.  The second run produces a pdf.
+The RTD site can be configured to watch for updates on a github repository.  A documentation update may be triggered when an update is pushed to the repository.  The entire documentation process is run twice.  The first run produces html.  The second run produces a pdf (if so instructed).
 
 NOTE: There is a rough execution time limit of about 900 seconds.  Trying to do more than that will cause a "timeout" error.
 
@@ -249,6 +252,7 @@ as RTD runs sphinx processing directly using `sphinx-build` and not the Makefile
 ##### PAPER
 
 The default value is empty (`PAPER=`).  There are two options currently available in the Makefile (a4 or letter).
+The `PAPER` argument has no impact on html rendered content.
 
 #### conf.py
 
@@ -274,19 +278,6 @@ NOTE: This command does not have any impact if an existing binary is found.
 
 This option activates the NCAR configuration file: `ncar/Doxyfile_ncar_rtd`
 
-### Local web server
-
-Python provides a way to quickly stand up a private web server for checking documentation. It requires knowledge of
-the IP address if you are using a remote server, otherwise `localhost` should work.
-
-You can start the server on any port. Port 8080 is shown here as an example.
-```bash
-python3 -m http.server 8080
-```
-
-After starting the server, you can browse to the known IP using `http://IP/` or if you are on the same
-machine use `http://localhost/`.
-
 # Software installation
 
 On a relatively bare system, you can install a fairly stable documentation pipeline.
@@ -346,7 +337,9 @@ PDF generation requires the following packages
 
 ### doxygen
 
-Download latest [source](https://www.doxygen.nl/download.html).  Latest is `doxygen-1.8.20.src.tar.gz`.
+You may choose to download the [source](https://www.doxygen.nl/download.html).
+
+Latest is `doxygen-1.8.20.src.tar.gz`.
 
 ```bash
 tar xzf doxygen-1.8.20.src.tar.gz
@@ -358,15 +351,20 @@ make
 sudo make install
 ```
 
-Make install attempts to place the compiled version into /usr/local/bin.  You can link to a
-specific executable within the virtual environment.   At this point we also recommend
-renaming `doxygen` to `doxygen-1.8.20` within `/usr/local/bin`.
+The makefile for doxygen attempts to install the compiled version into /usr/local/bin.
+You can link to a specific executable within the virtual environment.   At this point we
+also recommend renaming `doxygen` to `doxygen-1.8.20` within `/usr/local/bin`.
+
+NOTE: The makefile for the documentation framework will attempt to compile a local doxygen
+binary of version 1.8.13 if a binary cannot be found in the `$PATH`.
 
 #### Testing
 
-Currently, the majority of testing has been done with the following versions:
+A lot of manual testing has been completed using the following versions:
 * 1.8.13
+* 1.8.14
 * 1.8.19
+* 1.8.20
 
 ### Read the Docs
 
@@ -383,56 +381,6 @@ See Sphinx run options below.  We capture up to three logfiles for RTD.  The mai
 Logfiles were renamed to `*.txt` to allow easier access and viewing from most websites.
 Most websites force download of `*.log` files.
 
-### python3 virtual enviroment
-
-Setup a virtual environment for processing:
-
-```bash
-python3 -m venv venv/mom6Doc
-source venv/mom6Doc/bin/activate
-# cd to the docs directory within the MOM6 repo
-pip3 install -r requirements.txt
-```
-
-The `deactivate` command allows you to exit from the virtual environment.
-
-NOTE: RTD will not upgrade the sphinx module if `#egg=` is specified in the `requirements.txt` file.
-
-### debugging
-
-A useful commnad line tool for debugging sphinx and extensions is the python debugger.
-Add the following line to stop to any portion of the python code to create a break
-point.
-
-```python
-import pdb; pdb.set_trace()
-```
-
-Run `make html` without redirection to a log file.
-
-For only processing .dox files, run
-`make clean; make html DOXYGEN_CONF=Doxyfile_rtd_dox UPDATEHTMLEQS=Y`
-
-## Example execution
-
-The following example assumes a virtual environment as setup above using `mom6Doc`.
-The same environment is possible using anaconda.
-
-```
-$ source venv/mom6Doc/bin/activate
-(mom6Doc) $ cd docs
-(mom6Doc) $ make clean
-(mom6Doc) $ make html >& _build/html_log.txt
-(mom6Doc) $ make latexpdf >& _build/latex_log.txt
-```
-
-The last command may appear to hang.  On error, latex will request input from the keyboard.
-Press `R` and enter.  This will keep latex running to completion or stop after 100 errors
-are reached.
-
-Once the documentation is built, you can use a web browser to look around in the `_build`
-directory.
-
 # Credits
 
 ## 2020
@@ -442,10 +390,10 @@ to process the MOM6 documentation.  The versions are tagged and placed into the
 | Source | Modified | Version | Development |
 | ------ | -------- | ------- | ----------- |
 | [sphinx](https://github.com/sphinx-doc/sphinx) | [sphinx-3.2.1mom6.4](https://github.com/jr3cermak/sphinx) | B:3.2.1mom6.4 | B:dev |
-| [sphinxcontrib-autodoc-doxygen](https://github.com/rmcgibbo/sphinxcontrib-autodoc_doxygen) | [sphinxcontrib-autodoc-doxygen](https://github.com/jr3cermak/sphinxcontrib-autodoc_doxygen) | T:0.7.12 | B:dev |
+| [sphinxcontrib-autodoc-doxygen](https://github.com/rmcgibbo/sphinxcontrib-autodoc_doxygen) | [sphinxcontrib-autodoc-doxygen](https://github.com/jr3cermak/sphinxcontrib-autodoc_doxygen) | T:0.7.13 | B:dev |
 | [sphinx-fortran](https://github.com/VACUMM/sphinx-fortran) | [sphinx-fortran](https://github.com/jr3cermak/sphinx-fortran) | T:1.2.2 | B:dev |
 | [flint](https://github.com/marshallward/flint) | [flint](https://github.com/jr3cermak/flint) | T:0.0.1 | B:dev |
-| [MOM6](https://github.com/NOAA-GFDL/MOM6) | [esmg-docs](https://github.com/ESMG/MOM6/tree/esmg-docs) | [esmg-docs](https://github.com/jr3cermak/MOM6/tree/esmg-docs) | B:[dev/rob](https://github.com/jr3cermak/MOM6/tree/dev-rob) |
+| [MOM6](https://github.com/NOAA-GFDL/MOM6) | [esmg-docs](https://github.com/ESMG/MOM6/tree/esmg-docs) | [esmg-docs](https://github.com/ESMG/MOM6/tree/esmg-docs) | B:[esmg-test](https://github.com/jr3cermak/MOM6/tree/esmg-test) |
 
 T: tag B: branch
 

docs/conf.py

@@ -181,7 +181,7 @@ def latexPassthru(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', 'src', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'details', 'src', 'Thumbs.db', '.DS_Store']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/details/general.md

@@ -39,3 +39,71 @@ latex escaped math in equations.  If a latex string for `\theta` is read in as
 tab (`\t`) and cause mahem with the processing.
 
 Reference: [string literals](https://docs.python.org/3/reference/lexical_analysis.html?#literals)
+
+# Debugging
+
+## python3 virtual enviroment
+
+Setup a virtual environment for processing:
+
+```bash
+python3 -m venv venv/mom6Doc
+source venv/mom6Doc/bin/activate
+# cd to the docs directory within the MOM6 repo
+pip3 install -r requirements.txt
+```
+
+The `deactivate` command allows you to exit from the virtual environment.
+
+NOTE: RTD will not upgrade the sphinx module if `#egg=` is specified in the `requirements.txt` file.
+
+### debugging
+
+A useful commnad line tool for debugging sphinx and extensions is the python debugger.
+Add the following line to stop to any portion of the python code to create a break
+point.
+
+```python
+import pdb; pdb.set_trace()
+```
+
+Run `make html` without redirection to a log file.
+
+For only processing .dox files and some specific F90 files, edit and use the
+`Doxyfile_rtd_dox` file.  This limits the document processing to fewer files and
+allows for rapid testing.
+
+`make clean; make html DOXYGEN_CONF=Doxyfile_rtd_dox UPDATEHTMLEQS=Y`
+
+## Example execution
+
+The following example assumes a virtual environment as setup above using `mom6Doc`.
+A similar environment is possible using anaconda.
+
+```
+$ source venv/mom6Doc/bin/activate
+(mom6Doc) $ cd docs
+(mom6Doc) $ make clean
+(mom6Doc) $ make html >& _build/html_log.txt
+(mom6Doc) $ make latexpdf >& _build/latex_log.txt
+```
+
+The last command may appear to hang.  On error, latex will request input from the keyboard.
+Press `R` and enter.  This will keep latex running to completion or stop after 100 errors
+are reached.
+
+Once the documentation is built, you can use a web browser to look around in the `_build`
+directory.
+
+## Local web server
+
+Python provides a way to quickly stand up a private web server for checking documentation. It requires knowledge of
+the IP address if you are using a remote server, otherwise `localhost` should work.
+
+You can start the server on any port. Port 8080 is shown here as an example.
+```bash
+python3 -m http.server 8080
+```
+
+After starting the server, you can browse to the known IP using `http://IP:8080/` or if you are on the same
+machine use `http://localhost:8080/`.