Merge branch 'main' into ufs-dev-PR253

Author: grantfirl

scm/doc/Makefile

@@ -13,6 +13,9 @@ latex:
 html:
 	python -m sphinx -T -b html -d _build/doctrees -D language=en TechGuide html
 
+open:
+	open html/index.html
+
 clean:
 	rm -fr _build html latex
 

scm/doc/README.md

@@ -2,16 +2,22 @@
 
 The SCM technical documentation/users' guide is written in [reStructured Text markup language (RST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). It is designed to be built with the [Sphinx documentation tool](https://www.sphinx-doc.org/en/master/index.html), and is documentation from the `main` branch is configured to build automatically on ReadTheDocs: https://ccpp-scm.readthedocs.io/en/latest/
 
-## Building docs locally
-
+## Building documentation locally
+### Quick Build
+```
+$ make html
+$ make open
+```
+
+### Detailed Build Instructions
 To build the HTML documentation locally (for example, when testing modifications to the documentation), you must have Sphinx [installed on your machine](https://www.sphinx-doc.org/en/master/usage/installation.html), as well as the required python packages listed in the `requirements.txt` file. Once the prerequisite software is installed, you can build the HTML documentation using the following commands:
 
-    python -m sphinx -T -b html -d _build/doctrees -D language=en . html
+    $ python -m sphinx -T -b html -d _build/doctrees -D language=en . html
+    $ open html/index.html
 
 To build a PDF locally, in addition to Sphinx you must have Perl as well as the Perl-based [`latexmk` utility](https://mg.readthedocs.io/latexmk.html#installation). You can then build a PDF using the following commands:
 
-    python -m sphinx -T -b latex -d _build/doctrees -D language=en . latex
-    latexmk -f -pdf -pdflatex="pdflatex" -use-make index.tex
+    $ python -m sphinx -T -b latex -d _build/doctrees -D language=en . latex
+    $ latexmk -f -pdf -pdflatex="pdflatex" -use-make index.tex
 
 In lieu of running the above commands manually, you can also use `make`. The command `make all` will build both HTML and PDF documentation, while `make html` and `make latex` will build HTML and PDF respectively.
-

scm/doc/TechGuide/chap_cases.rst

@@ -101,11 +101,25 @@ Case input data file (DEPHY format)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Development and Evaluation of Physics in atmospheric models (DEPHY)
-format is an internationally-adopted data format intended for use by SCM
+format is an internationally-adopted data format intended for use by SCMs
 and LESs. The initialization and forcing data for each case in the CCPP SCM
 repository is stored in a NetCDF (version 4) file. Additional cases in DEPHY
-format, not maintained by the DTC, can be cloned from the DEPHY-SCM repository,
-and run by providing the DEPHY-SCM file location to the SCM. For example:
+format, not maintained by the DTC, can be cloned from the `DEPHY-SCM
+<https://github.com/GdR-DEPHY/DEPHY-SCM>`__ repository, and run by providing the
+DEPHY-SCM file location to the SCM.
+
+   .. note::
+
+      Not all forcing methods available in external DEPHY-SCM cases are currently 
+      supported in the CCPP SCM. For example:
+   
+      - ``surface_forcing_moisture``: "beta", "mrsos" 
+      - ``surface_forcing_wind``: "ustar"
+      - ``surface_type``: "seaice"
+
+      Be sure to verify that the case you wish to run is compatible with the CCPP SCM.
+
+Example to run a DEPHY-SCM case:
 
 .. code:: bash
 

scm/doc/TechGuide/chap_quick.rst

@@ -711,7 +711,9 @@ If using the model on HPC resources and significant amounts of processor
 time is anticipated for the experiments, it will likely be necessary to
 submit a job through the HPC’s batch system. An example script has been
 included in the repository for running the model on Hera’s batch system
-(SLURM). It is located in ``ccpp-scm/scm/etc/scm_slurm_example.py``. Edit the ``job_name``, ``account``, etc. to suit your needs and
+(SLURM). Note, this is machine specific and might not be the optimal approach
+on other systems with different charging configurations.
+It is located in ``ccpp-scm/scm/etc/scm_slurm_example.py``. Edit the ``job_name``, ``account``, etc. to suit your needs and
 copy to the ``bin`` directory. The case name to be run is included in the ``command``
 variable. To use, invoke
 
@@ -723,8 +725,7 @@ from the ``bin`` directory.
 
 Additional details regarding the SCM may be found in the remainder of
 this guide. More information on the CCPP can be found in the CCPP
-Technical Documentation available at
-https://ccpp-techdoc.readthedocs.io/en/v7.0.0/.
+Technical Documentation available at https://ccpp-techdoc.readthedocs.io.
 
 .. _docker:
 

scm/doc/TechGuide/chap_repo.rst

@@ -49,7 +49,7 @@ Cubed-Sphere (FV3) dynamical core.
 | ``│   │   └── vert_coord_data`` - Contains data to calculate vertical coordinates (from GSM-based GFS only)
 | ``│   ├── doc``
 | ``│   │   └── TechGuide`` - Contains source code and other files for this User’s/Technical Guide
-| ``│   ├── etc`` - Contains case configuration, machine setup scripts, and plotting scripts
+| ``│   ├── etc`` - Contains case configuration, machine setup scripts, and plotting scripts. These might be machine dependent and not all scripts are supported
 | ``│   │   ├── CENTOS_docker_setup.sh`` - Contains machine setup for Docker container
 | ``│   │   ├── case_config`` - Contains case configuration files
 | ``│   │   ├── modules`` - Contains module files for loading build environments on both pre-configured and custom platforms