Add utility script documentation to the Users Guide, moved to standar…

…d sphinx directory structure and names (#514)
NOAA-EMC · Oct 7, 2024 · 60707e5 · 60707e5
1 parent 9d754c8
commit 60707e5
Show file tree

Hide file tree

Showing 37 changed files with 292 additions and 11 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -32,16 +32,15 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install sphinx sphinxcontrib-bibtex sphinx-rtd-theme numpy matplotlib pandas cartopy pandas cartopy f90nml netCDF4 xarray scipy 
+        pip install sphinx sphinxcontrib-bibtex sphinx-rtd-theme
     - name: Build docs
       run: |
-        cd rrfs-workflow/doc/UsersGuide
-        sphinx-apidoc -o source/ ../../ush/
+        cd rrfs-workflow/docs
         #sphinx-build -W --keep-going source build
         sphinx-build source build
     - uses: actions/upload-artifact@v4
       with:
         name: rrfs-workflow docs
         path: |
-          rrfs-workflow/doc/UsersGuide/build
+          rrfs-workflow/docs/build
         
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -17,7 +17,7 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: doc/UsersGuide/source/conf.py
+   configuration: docs/source/conf.py
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 # formats:
@@ -26,7 +26,7 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: doc/UsersGuide/requirements.txt
+   - requirements: docs/requirements.txt
 
 submodules:
    include:

diff --git a/doc/UsersGuide/source/_templates/.gitignore b/doc/UsersGuide/source/_templates/.gitignore
diff --git a/doc/UsersGuide/source/tables/.DS_Store b/doc/UsersGuide/source/tables/.DS_Store
diff --git a/doc/UsersGuide/Makefile → docs/Makefile b/doc/UsersGuide/Makefile → docs/Makefile
diff --git a/doc/UsersGuide/README → docs/README b/doc/UsersGuide/README → docs/README
diff --git a/doc/README.xml_templating.md → docs/README.xml_templating.md b/doc/README.xml_templating.md → docs/README.xml_templating.md
diff --git a/doc/Setup-RRFS.md → docs/Setup-RRFS.md b/doc/Setup-RRFS.md → docs/Setup-RRFS.md
diff --git a/doc/Setup-RTMA.md → docs/Setup-RTMA.md b/doc/Setup-RTMA.md → docs/Setup-RTMA.md
diff --git a/doc/UsersGuide/make.bat → docs/make.bat b/doc/UsersGuide/make.bat → docs/make.bat
diff --git a/doc/UsersGuide/requirements.txt → docs/requirements.txt b/doc/UsersGuide/requirements.txt → docs/requirements.txt
diff --git a/docs/source/HWP_tools.rst b/docs/source/HWP_tools.rst
@@ -0,0 +1,7 @@
+HWP\_tools module
+=================
+
+.. automodule:: HWP_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/Qmodules.rst b/docs/source/Qmodules.rst
@@ -0,0 +1,25 @@
+ush
+===
+
+.. toctree::
+   :maxdepth: 2
+
+   HWP_tools
+   UFS_plot_domains
+   blending_fv3
+   chgres_cold2fv3
+   create_diag_table_file
+   create_model_configure_file
+   create_ufs_configure_file
+   enspost_config
+   fill_jinja_template
+   fire_emiss_tools
+   fvcom_remap
+   generate_fire_emissions
+   get_crontab_contents
+   interp_tools
+   log_change
+   python_utils
+   rrfsfw_domain
+   set_namelist
+
diff --git a/doc/UsersGuide/source/Quickstart.rst → docs/source/Quickstart.rst b/doc/UsersGuide/source/Quickstart.rst → docs/source/Quickstart.rst
diff --git a/docs/source/UFS_plot_domains.rst b/docs/source/UFS_plot_domains.rst
@@ -0,0 +1,7 @@
+UFS\_plot\_domains module
+=========================
+
+.. automodule:: UFS_plot_domains
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/UsersGuide/source/_static/custom.css → docs/source/_static/custom.css b/doc/UsersGuide/source/_static/custom.css → docs/source/_static/custom.css
diff --git a/...sGuide/source/_static/theme_overrides.css → docs/source/_static/theme_overrides.css b/...sGuide/source/_static/theme_overrides.css → docs/source/_static/theme_overrides.css
diff --git a/docs/source/blending_fv3.rst b/docs/source/blending_fv3.rst
@@ -0,0 +1,7 @@
+blending\_fv3 module
+====================
+
+.. automodule:: blending_fv3
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/chgres_cold2fv3.rst b/docs/source/chgres_cold2fv3.rst
@@ -0,0 +1,7 @@
+chgres\_cold2fv3 module
+=======================
+
+.. automodule:: chgres_cold2fv3
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/UsersGuide/source/conf.py → docs/source/conf.py b/doc/UsersGuide/source/conf.py → docs/source/conf.py
@@ -15,7 +15,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('../../../ush'))
+sys.path.insert(0, os.path.abspath('../../ush'))
 
 # -- Project information -----------------------------------------------------
 

diff --git a/docs/source/create_diag_table_file.rst b/docs/source/create_diag_table_file.rst
@@ -0,0 +1,7 @@
+create\_diag\_table\_file module
+================================
+
+.. automodule:: create_diag_table_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/create_model_configure_file.rst b/docs/source/create_model_configure_file.rst
@@ -0,0 +1,7 @@
+create\_model\_configure\_file module
+=====================================
+
+.. automodule:: create_model_configure_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/create_ufs_configure_file.rst b/docs/source/create_ufs_configure_file.rst
@@ -0,0 +1,7 @@
+create\_ufs\_configure\_file module
+===================================
+
+.. automodule:: create_ufs_configure_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/enspost_config.rst b/docs/source/enspost_config.rst
@@ -0,0 +1,7 @@
+enspost\_config module
+======================
+
+.. automodule:: enspost_config
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/fill_jinja_template.rst b/docs/source/fill_jinja_template.rst
@@ -0,0 +1,7 @@
+fill\_jinja\_template module
+============================
+
+.. automodule:: fill_jinja_template
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/fire_emiss_tools.rst b/docs/source/fire_emiss_tools.rst
@@ -0,0 +1,7 @@
+fire\_emiss\_tools module
+=========================
+
+.. automodule:: fire_emiss_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/fvcom_remap.rst b/docs/source/fvcom_remap.rst
@@ -0,0 +1,7 @@
+fvcom\_remap module
+===================
+
+.. automodule:: fvcom_remap
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/generate_fire_emissions.rst b/docs/source/generate_fire_emissions.rst
@@ -0,0 +1,7 @@
+generate\_fire\_emissions module
+================================
+
+.. automodule:: generate_fire_emissions
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/get_crontab_contents.rst b/docs/source/get_crontab_contents.rst
@@ -0,0 +1,7 @@
+get\_crontab\_contents module
+=============================
+
+.. automodule:: get_crontab_contents
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/UsersGuide/source/index.rst → docs/source/index.rst b/doc/UsersGuide/source/index.rst → docs/source/index.rst
diff --git a/docs/source/interp_tools.rst b/docs/source/interp_tools.rst
@@ -0,0 +1,7 @@
+interp\_tools module
+====================
+
+.. automodule:: interp_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/log_change.rst b/docs/source/log_change.rst
@@ -0,0 +1,7 @@
+log\_change module
+==================
+
+.. automodule:: log_change
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,25 @@
+Utility Scripts
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   HWP_tools
+   UFS_plot_domains
+   blending_fv3
+   chgres_cold2fv3
+   create_diag_table_file
+   create_model_configure_file
+   create_ufs_configure_file
+   enspost_config
+   fill_jinja_template
+   fire_emiss_tools
+   fvcom_remap
+   generate_fire_emissions
+   get_crontab_contents
+   interp_tools
+   log_change
+   python_utils
+   rrfsfw_domain
+   set_namelist
+
diff --git a/docs/source/python_utils.rst b/docs/source/python_utils.rst
@@ -0,0 +1,117 @@
+python\_utils package
+=====================
+
+Submodules
+----------
+
+python\_utils.check\_for\_preexist\_dir\_file module
+----------------------------------------------------
+
+.. automodule:: python_utils.check_for_preexist_dir_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.check\_var\_valid\_value module
+---------------------------------------------
+
+.. automodule:: python_utils.check_var_valid_value
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.config\_parser module
+-----------------------------------
+
+.. automodule:: python_utils.config_parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.create\_symlink\_to\_file module
+----------------------------------------------
+
+.. automodule:: python_utils.create_symlink_to_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.define\_macos\_utilities module
+---------------------------------------------
+
+.. automodule:: python_utils.define_macos_utilities
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.environment module
+--------------------------------
+
+.. automodule:: python_utils.environment
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.filesys\_cmds\_vrfy module
+----------------------------------------
+
+.. automodule:: python_utils.filesys_cmds_vrfy
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.fv3write\_parms\_lambert module
+---------------------------------------------
+
+.. automodule:: python_utils.fv3write_parms_lambert
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.misc module
+-------------------------
+
+.. automodule:: python_utils.misc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.print\_input\_args module
+---------------------------------------
+
+.. automodule:: python_utils.print_input_args
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.print\_msg module
+-------------------------------
+
+.. automodule:: python_utils.print_msg
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.run\_command module
+---------------------------------
+
+.. automodule:: python_utils.run_command
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+python\_utils.xml\_parser module
+--------------------------------
+
+.. automodule:: python_utils.xml_parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: python_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/UsersGuide/source/references.bib → docs/source/references.bib b/doc/UsersGuide/source/references.bib → docs/source/references.bib
diff --git a/docs/source/rrfsfw_domain.rst b/docs/source/rrfsfw_domain.rst
@@ -0,0 +1,7 @@
+rrfsfw\_domain module
+=====================
+
+.. automodule:: rrfsfw_domain
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/set_namelist.rst b/docs/source/set_namelist.rst
@@ -0,0 +1,7 @@
+set\_namelist module
+====================
+
+.. automodule:: set_namelist
+   :members:
+   :undoc-members:
+   :show-inheritance: