[develop]: Update python docstrings and generate preliminary technica…

…l documentation (#1131) * Initial implementation of SRW App technical documentation. Adds a section called "Technical Documentation" to the SRW App docs. * This update also removes outdated/redundant text files in doc (i.e., RUNTIME and INSTALL). --------- Co-authored-by: gspetro <[email protected]> Co-authored-by: Michael Lueken <[email protected]>
ufs-community · Oct 2, 2024 · 13d3ce5 · 13d3ce5
1 parent 1b01c64
commit 13d3ce5
Show file tree

Hide file tree

Showing 88 changed files with 1,616 additions and 961 deletions.
diff --git a/.gitignore b/.gitignore
@@ -23,6 +23,7 @@ ush/python_utils/__pycache__/
 ush/python_utils/workflow-tools/
 ush/*.swp
 conda_loc
+*/.DS_Store
 
 *.swp
 __pycache__
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -28,8 +28,4 @@ python:
    install:
    - requirements: doc/requirements.txt
 
-submodules:
-   include:
-   - hpc-stack-mod
-   recursive: true
 
diff --git a/doc/INSTALL b/doc/INSTALL
diff --git a/doc/README b/doc/README
@@ -9,6 +9,7 @@ Steps to build and use the Sphinx documentation tool:
     pip install sphinx
     pip install sphinxcontrib-bibtex
     pip install sphinx-rtd-theme
+    pip install sphinxcontrib.autoyaml
 
     One approach that has worked to resolve "Module Not Found" errors for users with MacPorts package manager: 
     $ sudo port install py-six  # may not be necessary

diff --git a/doc/RUNTIME b/doc/RUNTIME
diff --git a/doc/TechDocs/index.rst b/doc/TechDocs/index.rst
@@ -0,0 +1,8 @@
+Technical Documentation
+===========================
+
+.. toctree::
+   :maxdepth: 3
+
+   tests/index
+   ush/modules
diff --git a/doc/TechDocs/tests/WE2E/WE2E_summary.rst b/doc/TechDocs/tests/WE2E/WE2E_summary.rst
@@ -0,0 +1,7 @@
+WE2E\_summary module
+====================
+
+.. automodule:: WE2E_summary
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/tests/WE2E/modules.rst b/doc/TechDocs/tests/WE2E/modules.rst
@@ -0,0 +1,11 @@
+WE2E
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   WE2E_summary
+   monitor_jobs
+   print_test_info
+   run_WE2E_tests
+   utils
diff --git a/doc/TechDocs/tests/WE2E/monitor_jobs.rst b/doc/TechDocs/tests/WE2E/monitor_jobs.rst
@@ -0,0 +1,7 @@
+monitor\_jobs module
+====================
+
+.. automodule:: monitor_jobs
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/tests/WE2E/print_test_info.rst b/doc/TechDocs/tests/WE2E/print_test_info.rst
@@ -0,0 +1,7 @@
+print\_test\_info module
+========================
+
+.. automodule:: print_test_info
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/tests/WE2E/run_WE2E_tests.rst b/doc/TechDocs/tests/WE2E/run_WE2E_tests.rst
@@ -0,0 +1,7 @@
+run\_WE2E\_tests module
+=======================
+
+.. automodule:: run_WE2E_tests
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/tests/WE2E/utils.rst b/doc/TechDocs/tests/WE2E/utils.rst
@@ -0,0 +1,7 @@
+utils module
+============
+
+.. automodule:: utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/tests/index.rst b/doc/TechDocs/tests/index.rst
@@ -0,0 +1,7 @@
+tests
+======
+
+.. toctree::
+   :maxdepth: 3
+
+   WE2E/modules
diff --git a/doc/TechDocs/ush/UFS_plot_domains.rst b/doc/TechDocs/ush/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/TechDocs/ush/calculate_cost.rst b/doc/TechDocs/ush/calculate_cost.rst
@@ -0,0 +1,7 @@
+calculate\_cost module
+======================
+
+.. automodule:: calculate_cost
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/ush/check_python_version.rst b/doc/TechDocs/ush/check_python_version.rst
@@ -0,0 +1,7 @@
+check\_python\_version module
+=============================
+
+.. automodule:: check_python_version
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/ush/config_utils.rst b/doc/TechDocs/ush/config_utils.rst
@@ -0,0 +1,7 @@
+config\_utils module
+====================
+
+.. automodule:: config_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/ush/create_aqm_rc_file.rst b/doc/TechDocs/ush/create_aqm_rc_file.rst
@@ -0,0 +1,7 @@
+create\_aqm\_rc\_file module
+============================
+
+.. automodule:: create_aqm_rc_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/ush/create_diag_table_file.rst b/doc/TechDocs/ush/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/doc/TechDocs/ush/create_model_configure_file.rst b/doc/TechDocs/ush/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/doc/TechDocs/ush/create_ufs_configure_file.rst b/doc/TechDocs/ush/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/doc/TechDocs/ush/generate_FV3LAM_wflow.rst b/doc/TechDocs/ush/generate_FV3LAM_wflow.rst
@@ -0,0 +1,7 @@
+generate\_FV3LAM\_wflow module
+==============================
+
+.. automodule:: generate_FV3LAM_wflow
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/ush/get_crontab_contents.rst b/doc/TechDocs/ush/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/TechDocs/ush/link_fix.rst b/doc/TechDocs/ush/link_fix.rst
@@ -0,0 +1,7 @@
+link\_fix module
+================
+
+.. automodule:: link_fix
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/TechDocs/ush/modules.rst b/doc/TechDocs/ush/modules.rst
@@ -0,0 +1,29 @@
+ush
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   UFS_plot_domains
+   calculate_cost
+   check_python_version
+   config_utils
+   create_aqm_rc_file
+   create_diag_table_file
+   create_model_configure_file
+   create_ufs_configure_file
+   generate_FV3LAM_wflow
+   get_crontab_contents
+   link_fix
+   mrms_pull_topofhour
+   python_utils
+   retrieve_data
+   run_srw_tests
+   set_cycle_dates
+   set_fv3nml_ens_stoch_seeds
+   set_fv3nml_sfc_climo_filenames
+   set_gridparams_ESGgrid
+   set_gridparams_GFDLgrid
+   set_predef_grid_params
+   setup
+   update_input_nml
diff --git a/doc/TechDocs/ush/mrms_pull_topofhour.rst b/doc/TechDocs/ush/mrms_pull_topofhour.rst
@@ -0,0 +1,7 @@
+mrms\_pull\_topofhour module
+============================
+
+.. automodule:: mrms_pull_topofhour
+   :members:
+   :undoc-members:
+   :show-inheritance: