Merge pull request #255 from ilaflott/update-fre-cmor-doc2

basic doc updates
NOAA-GFDL · Nov 7, 2024 · 5f1a6ed · 5f1a6ed
2 parents 3288f22 + 05052d0
commit 5f1a6ed
Show file tree

Hide file tree

Showing 12 changed files with 104 additions and 65 deletions.
diff --git a/docs/badges.rst b/docs/badges.rst
@@ -1,3 +1,4 @@
+.. this file is explicitly for the hyperlinkage in the base README.md to the badge image files
 ======
 Badges
 ======

diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst
@@ -1,3 +1,5 @@
+.. last updated early Nov 2024.
+   could use some refinement
 ===========================
 Documentation-Documentation
 ===========================
@@ -16,9 +18,9 @@ How to Contribute to ``fre-cli``'s documentation
    * On github, navigate to your ``fre-cli`` fork, and click “settings”
    * In “settings”, click “pages”
    * In “pages”, under “build and deployment”, make sure “source” is set to “Deploy from a branch”
-   * Under that, find “Branch”, make sure the branch selected is ``gh-pages``. 
-   * The branch ``gh-pages`` is “automagic”- i.e. do not change anything about it nor create a new one,
-	 nor interact with anything in that branch directly.
+   * Under that, find “Branch”, make sure the branch selected is ``gh-pages``
+   * The branch ``gh-pages`` is "automagic”- i.e. do not change anything about it nor create a new one,
+	 nor interact with anything in that branch directly
 
 
 2. enable workflows for your fork
@@ -28,17 +30,17 @@ How to Contribute to ``fre-cli``'s documentation
    * Enable running the workflow actions assoc with the ``fre-cli`` repo under ``.github/workflows``
 
 
-3. run your forks first workflow
+3. run your fork's first workflow
 
-   * The documentation builds as the last steps to ``create_test_conda_env.yml`` when theres a push to ``main``.
-	 To get your first workflow run on your fork, comment out the ``github.ref == ‘refs/heads/main’`` bit
+   * The documentation builds as the last steps to ``create_test_conda_env.yml`` when theres a push to ``main``
+   * To get your first workflow run on your fork, comment out the ``github.ref == ‘refs/heads/main’`` bit
 	 so that it runs when you push to any branch, and make a small, trivial, commit somewhere to your
-	 remote fork.
+	 remote fork
    * You should be able to find the deployed webpage from a successful workflow at
-	 https://your_username.github.io/fre-cli (if you did not change the fork’s name from ``fre-cli``, that is).
+	 https://your_username.github.io/fre-cli (if you did not change the fork’s name from ``fre-cli``, that is)
    * If you’re only editing docs, you can make the turn-around time on your workflow ~3 min faster by
-   commenting-out the ``pylint`` and ``pytest`` steps in ``create_test_conda_env.yml``, and disable running the
-   ``build_conda.yml`` workflow
+	 commenting-out the ``pylint`` and ``pytest`` steps in ``create_test_conda_env.yml``, and disable running the
+	 ``build_conda.yml`` workflow
 
 
 
diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst
@@ -1,3 +1,4 @@
+.. NEEDS UPDATING #TODO
 ===============
 Developer Usage
 ===============

diff --git a/docs/fre_app.rst b/docs/fre_app.rst
@@ -0,0 +1,6 @@
+.. NEEDS UPDATING #TODO
+``generate-time-averages``
+--------------------------
+
+``regrid_xy``
+-------------
diff --git a/docs/fre_catalog.rst b/docs/fre_catalog.rst
@@ -0,0 +1,12 @@
+.. NEEDS UPDATING #TODO
+``builder``
+-----------
+ Generate a catalog
+* Builds json and csv format catalogs from user input directory path
+* Minimal Syntax: ``fre catalog builder -i [input path] -o [output path]``
+* Module(s) needed: n/a
+* Example: ``fre catalog builder -i /archive/am5/am5/am5f3b1r0/c96L65_am5f3b1r0_pdclim1850F/gfdl.ncrc5-deploy-prod-openmp/pp -o ~/output --overwrite``
+
+``validate``
+------------
+Validate the catalog
diff --git a/docs/fre_cmor.rst b/docs/fre_cmor.rst
@@ -0,0 +1,5 @@
+.. last updated Nov 2024
+``run``
+-------   
+
+
diff --git a/docs/fre_make.rst b/docs/fre_make.rst
@@ -0,0 +1,4 @@
+.. NEEDS UPDATING #TODO
+1. ``run-fremake``
+
+* placehold
diff --git a/docs/fre_pp.rst b/docs/fre_pp.rst
@@ -0,0 +1,16 @@
+.. NEEDS UPDATING #TODO
+``configure``
+-------------
+
+* Postprocessing yaml configuration
+* Minimal Syntax: ``fre pp configure -y [user-edit yaml file]``
+* Module(s) needed: n/a
+* Example: ``fre pp configure -y /home/$user/pp/ue2/user-edits/edits.yaml``
+
+``checkout``
+------------
+
+* Checkout template file and clone gitlab.gfdl.noaa.gov/fre2/workflows/postprocessing.git repository
+* Minimal Syntax: ``fre pp checkout -e [experiment name] -p [platform name] -t [target name]``
+* Module(s) needed: n/a
+* Example: ``fre pp checkout -e c96L65_am5f4b4r0_amip -p gfdl.ncrc5-deploy -t prod-openmp``
diff --git a/docs/fre_yamltools.rst b/docs/fre_yamltools.rst
@@ -0,0 +1,6 @@
+.. NEEDS UPDATING #TODO
+   
+``combine-yamls``
+-----------------
+
+* placehold
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,6 +6,8 @@
 Welcome to Fre-Cli's documentation!
 ===================================
 
+.. the entry in the toc must be the .rst filename.
+   what shows in the webpage is the first header or title
 .. toctree::
    :maxdepth: 3
    :caption: Contents:

diff --git a/docs/setup.rst b/docs/setup.rst
@@ -1,3 +1,4 @@
+.. NEEDS UPDATING #TODO
 =====
 Setup
 =====

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -1,12 +1,13 @@
-=====
-Usage
-=====
+.. NEEDS UPDATING #TODO
+=============
+Usage-By-Tool
+=============
 
 for setup, see the setup section.
 
 
-Calling ``fre``
-===============
+``fre``
+=======
 
 Brief rundown of commands also provided below:
 
@@ -23,80 +24,62 @@ Brief rundown of commands also provided below:
   *entry point*. Without it, the call would be instead, something like ``python fre/fre.py``
 
 
-Tools
-=====
-
-A few subtools are currently in development:
-
+``fre app``
+===========
 
-fre app
--------
-
-1. ``generate-time-averages``
-2. ``regrid_xy``
+.. include:: fre_app.rst
 
 
-fre catalog
------------
+``fre catalog``
+===============
 
-1. ``builder`` Generate a catalog
+.. include:: fre_catalog.rst
 
-* Builds json and csv format catalogs from user input directory path
-* Minimal Syntax: ``fre catalog builder -i [input path] -o [output path]``
-* Module(s) needed: n/a
-* Example: ``fre catalog builder -i /archive/am5/am5/am5f3b1r0/c96L65_am5f3b1r0_pdclim1850F/gfdl.ncrc5-deploy-prod-openmp/pp -o ~/output --overwrite``
 
-2. ``validate`` Validate the catalog
+``fre cmor``
+============
 
+.. include:: fre_cmor.rst
 
-fre cmor
---------
+
+``fre make``
+============
 
-1. ``run``
+.. include:: fre_make.rst
+
 
-* placehold
+``fre pp``
+==========
 
-
-fre make
---------
+.. include:: fre_pp.rst
 
-1. ``run-fremake``
 
-* placehold
+``fre yamltools``
+=================
 
-
-fre pp
-------
+.. include:: fre_yamltools.rst
 
-1. ``configure`` 
 
-* Postprocessing yaml configuration
-* Minimal Syntax: ``fre pp configure -y [user-edit yaml file]``
-* Module(s) needed: n/a
-* Example: ``fre pp configure -y /home/$user/pp/ue2/user-edits/edits.yaml``
+``fre check``
+=============
 
-2. ``checkout``
+**not-yet-implemented**
 
-* Checkout template file and clone gitlab.gfdl.noaa.gov/fre2/workflows/postprocessing.git repository
-* Minimal Syntax: ``fre pp checkout -e [experiment name] -p [platform name] -t [target name]``
-* Module(s) needed: n/a
-* Example: ``fre pp checkout -e c96L65_am5f4b4r0_amip -p gfdl.ncrc5-deploy -t prod-openmp``
 
+``fre list``
+============
 
-fre yamltools
--------------
+**not-yet-implemented**
 
-1. ``combine-yamls``
 
-* placehold
+``fre run``
+===========
 
+**not-yet-implemented**
 
-not-yet-implemented
--------------------
 
-#. ``fre check``
-#. ``fre list``
-#. ``fre run``
-#. ``fre test``
+``fre test``
+============
 
+**not-yet-implemented**