Merge pull request #262 from singhd789/main

FRE make documentation update

docs/fre_make.rst

@@ -1,4 +1,59 @@
-.. NEEDS UPDATING #TODO
-1. ``run-fremake``
+``create-checkout``
+-------------
 
-* placehold
+``fre make create-checkout [options]``
+   - Purpose: Creates the checkout script and can check out source code (with execute option)
+   - Options:
+        - `-y, --yamlfile [experiment yaml] (required)`
+        - `-p, --platform [platform] (required)`
+        - `-t, --target [target] (required)`
+        - `-j, --jobs [number of jobs to run simultneously]`
+        - `-npc, --no-parallel-checkout (for container build)`
+        - `-e, --execute`
+
+``create-makefile`` 
+-------------
+
+``fre make create-makefile [options]``
+   - Purpose: Creates the makefile
+   - Options:
+        - `-y, --yamlfile [experiment yaml] (required)`
+        - `-p, --platform [platform] (required)`
+        - `-t, --target [target] (required)`
+
+``create-compile``
+-------------
+
+``fre make create-compile [options]``
+   - Purpose: Creates the compile script and compiles the model (with execute option)
+   - Options:
+        - `-y, --yamlfile [experiment yaml] (required)`
+        - `-p, --platform [platform] (required)`
+        - `-t, --target [target] (required)`
+        - `-j, --jobs [number of jobs to run simultneously]`
+        - `-n, --parallel [number of concurrent modile compiles]`
+        - `-e, --execute`
+
+``create-dockerfile``
+-------------
+
+``fre make create-dockerfile [options]``
+   - Purpose: Creates the dockerfile and creates the container (with execute option)
+   - With the creation of the dockerfile, the Makefile, checkout script, and any other necessary script is copied into the container from a temporary location
+   - Options:
+        - `-y, --yamlfile [experiment yaml] (required)`
+        - `-p, --platform [platform] (required)`
+        - `-t, --target [target] (required)`
+
+``run-fremake``
+-------------
+
+``fre make run-fremake [options]``
+   - Purpose: Create the checkout script, Makefile, compile script, and dockerfile (platform dependent) for the compilation of the model
+   - Options:
+        - `-y, --yamlfile [experiment yaml] (required)`
+        - `-p, --platform [platform] (required)`
+        - `-t, --target [target] (required)`
+        - `-npc, --no-parallel-checkout (for container build)`
+        - `-j, --jobs [number of jobs to run simultneously]`
+        - `-n, --parallel [number of concurrent modile compiles]`

docs/index.rst

@@ -14,6 +14,7 @@ Welcome to ``fre-cli``'s documentation!
 
    setup
    usage
+   tool_guides
    developer_usage
    contributing_to_doc
    badges

docs/tool_guides.rst

@@ -0,0 +1,156 @@
+.. NEEDS UPDATING #TODO
+=============
+Tool Guides
+=============
+
+Guides for the process in which subtools are used with tools.
+
+
+``fre app``
+============
+
+``fre catalog``
+============
+
+``fre cmor``
+============
+
+.. _fre-make-guide:
+
+``fre make guide``
+============
+
+1. Bare-metal Build:
+
+.. code-block::
+
+  # Create checkout script
+  fre make create-checkout -y [model yaml file] -p [platform] -t [target]
+
+  # Create and run checkout script
+  fre make create-checkout -y [model yaml file] -p [platform] -t [target] --execute
+
+  # Create Makefile
+  fre make create-makefile -y [model yaml file] -p [platform] -t [target]
+
+  # Creat the compile script
+  fre make create-compile -y [model yaml file] -p [platform] -t [target]
+
+  # Create and run the compile script
+  fre make create-compile -y [model yaml file] -p [platform] -t [target] --execute
+
+  # Run all of fremake
+  fre make run-fremake -y [model yaml file] -p [platform] -t [target] [other options...]
+
+2. Container Build:
+
+For the container build, parallel checkouts are not supported, so the `-npc` options must be used for the checkout script. In addition the platform must be a container platform.
+
+Users will not be able to create containers unless they have podman access on gaea.
+
+.. code-block::
+
+  # Create checkout script
+  fre make create-checkout -y [model yaml file] -p [CONTAINER PLATFORM] -t [target] -npc
+
+  # Create and run checkout script
+  fre make create-checkout -y [model yaml file] -p [CONTAINER PLATFORM] -t [target] --execute
+
+  # Create Makefile
+  fre make create-makefile -y [model yaml file] -p [CONTAINER PLATFORM] -t [target]
+
+  # Create a Dockerfile
+  fre make create-dockerfile -y [model yaml file] -p [CONTAINER PLATFORM] -t [target]
+
+  # Create and run the Dockerfile
+  fre make create-dockerfile -y [model yaml file] -p [CONTAINER PLATFORM] -t [target] --execute
+
+
+**Quickstart**
+
+1. Bare-metal Build:
+
+.. code-block::
+
+  # Create checkout script
+  fre make create-checkout -y am5.yaml -p ncrc5.intel23 -t prod
+
+  # Create and run checkout script
+  fre make create-checkout -y am5.yaml -p ncrc5.intel23 -t prod --execute
+
+  # Create Makefile
+  fre make create-makefile -y am5.yaml -p ncrc5.intel23 -t prod
+
+  # Create the compile script
+  fre make create-compile -y am5.yaml -p ncrc5.intel23 -t prod
+
+  # Create and run the compile script
+  fre make create-compile -y am5.yaml -p ncrc5.intel23 -t prod --execute
+
+2. Bare-metal Build Multi-target:
+
+.. code-block::
+
+  # Create checkout script
+  fre make create-checkout -y am5.yaml -p ncrc5.intel23 -t prod -t debug
+
+  # Create and run checkout script
+  fre make create-checkout -y am5.yaml -p ncrc5.intel23 -t prod -t debug --execute
+
+  # Create Makefile
+  fre make create-makefile -y am5.yaml -p ncrc5.intel23 -t prod -t debug
+
+  # Create the compile script
+  fre make create-compile -y am5.yaml -p ncrc5.intel23 -t prod -t debug
+
+  # Create and run the compile script
+  fre make create-compile -y am5.yaml -p ncrc5.intel23 -t prod -t debug --execute
+
+3. Container Build:
+
+In order for the container to build successfully, a `-npc`, or `--no-parallel-checkout` is needed.
+
+.. code-block::
+
+  # Create checkout script
+  fre make create-checkout -y am5.yaml -p hpcme.2023 -t prod -npc
+
+  # Create and run checkout script
+  fre make create-checkout -y am5.yaml -p hpcme.2023 -t prod -npc --execute
+
+  # Create Makefile
+  fre make create-makefile -y am5.yaml -p hpcme.2023 -t prod
+
+  # Create Dockerfile
+  fre make create-dockerfile -y am5.yaml -p hpcme.2023 -t prod
+
+  # Create and run the Dockerfile
+  fre make create-dockerfile -y am5.yaml -p hpcme.2023 -t prod --execute
+
+4. Run all of fremake:
+
+.. code-block::
+
+  # Bare-metal
+  fre make run-fremake -y am5.yaml -p ncrc5.intel23 -t prod
+
+  # Container
+  fre make run-fremake -y am5.yaml -p hpcme.2023 -t prod -npc
+
+``fre pp``
+============
+
+``fre yamltools``
+============
+
+``fre check``
+============
+
+``fre list``
+============
+
+``fre run``
+============
+
+``fre test``
+============

docs/usage.rst

@@ -53,8 +53,22 @@ intercomparisons (MIPs) using the ``cmor`` module is, quite cleverly, referred t
 ``fre make``
 ============
 
+Through the fre-cli, `fre make` can be used to create and run a checkout script, makefile, and compile a model.
+
+Fremake Canopy Supports:
+   - multiple targets; use `-t` flag to define each target
+   - bare-metal build
+   - container creation
+   - parallel checkouts for bare-metal build**
+
+** **Note: Users will not be able to create containers without access to podman**
+
 .. include:: fre_make.rst
-
+
+Guide and quickstart to `fre make` subtools:
+
+:ref:`fre-make-guide`
+
 
 ``fre pp``
 ==========