deploy: 6fc6105

NOAA-GFDL · Apr 19, 2024 · a0be7f7 · a0be7f7
commit a0be7f7
Show file tree

Hide file tree

Showing 76 changed files with 8,510 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 3d1206e6244c47281116be3e17fbec29
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.doctrees/FAQ.doctree b/.doctrees/FAQ.doctree
diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle
diff --git a/.doctrees/index.doctree b/.doctrees/index.doctree
diff --git a/.doctrees/setup.doctree b/.doctrees/setup.doctree
diff --git a/.doctrees/subtools.doctree b/.doctrees/subtools.doctree
diff --git a/.doctrees/usage.doctree b/.doctrees/usage.doctree
diff --git a/.nojekyll b/.nojekyll
diff --git a/FAQ.html b/FAQ.html
@@ -0,0 +1,112 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>FAQ &mdash; Fre-Cli 1.0 documentation</title>
+      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+      <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+      <link rel="stylesheet" href="_static/fonts.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+        <script src="_static/jquery.js?v=5d32c60e"></script>
+        <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script src="_static/documentation_options.js?v=f2a433a1"></script>
+        <script src="_static/doctools.js?v=9a2dae69"></script>
+        <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="prev" title="Subtools" href="subtools.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+
+
+
+          <a href="index.html" class="icon icon-home">
+            Fre-Cli
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="setup.html">Setup</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
+<li class="toctree-l1"><a class="reference internal" href="subtools.html">Subtools</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">FAQ</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="index.html">Fre-Cli</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
+      <li class="breadcrumb-item active">FAQ</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="_sources/FAQ.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <section id="faq">
+<h1>FAQ<a class="headerlink" href="#faq" title="Link to this heading"></a></h1>
+</section>
+
+
+           </div>
+          </div>
+          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+        <a href="subtools.html" class="btn btn-neutral float-left" title="Subtools" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+    </div>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2024, Bennett Chang.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>
diff --git a/_sources/FAQ.rst.txt b/_sources/FAQ.rst.txt
@@ -0,0 +1,2 @@
+FAQ
+===
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,23 @@
+.. Fre-Cli documentation master file, created by
+   sphinx-quickstart on Wed Mar  6 22:28:21 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Fre-Cli's documentation!
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   setup
+   usage
+   subtools
+   FAQ
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/_sources/setup.rst.txt b/_sources/setup.rst.txt
@@ -0,0 +1,32 @@
+Setup
+=====
+
+Need to set up Conda environment first and foremost
+
+If on workstation:
+module load conda
+
+Create new Conda environment
+conda create -n [environmentName]
+
+Append necessary channels
+conda config --append channels noaa-gfdl
+conda config --append channels conda-forge
+
+Run conda install on needed dependencies
+conda install noaa-gfdl::fre-cli should install the CLI package located at https://anaconda.org/NOAA-GFDL/fre-cli created from the meta.yaml file
+
+All other dependencies used by the tools are installed along with this install (configured inside the meta.yaml), with the exception of local modules
+setup.py file allows fre.py to be ran with fre as the entry point on the command line instead of python fre.py
+
+Enter commands and follow --help messages for guidance (brief rundown of commands also provided below)
+
+If the user just runs fre, it will list all the command groups following fre, such as run, make, pp, etc. and once the user specifies a command group, the list of available subcommands for that group will be shown
+
+Commands that require arguments to run will alert user about missing arguments, and will also list the rest of the optional parameters if --help is executed
+
+Argument flags are not positional, can be specified in any order as long as they are specified
+
+Can run directly from any directory, no need to clone repository
+
+May need to deactivate environment and reactivate it in order for changes to apply
diff --git a/_sources/subtools.rst.txt b/_sources/subtools.rst.txt
@@ -0,0 +1,20 @@
+Subtools
+========
+
+frecheck
+--------
+
+frelist
+-------
+
+fremake
+-------
+
+frepp
+-----
+
+frerun
+------
+
+fretest
+-------
diff --git a/_sources/usage.rst.txt b/_sources/usage.rst.txt
@@ -0,0 +1,156 @@
+Usage
+=====
+
+User Usage
+----------
+
+**Conda environment set up**
+
+Load Conda
+
+.. code-block::console
+ module load conda
+
+Create new Conda environment
+
+.. code-block::console
+ conda create -n [environmentName]
+
+Append necessary channels
+
+.. code-block::console
+ conda config --append channels noaa-gfdl
+ conda config --append channels conda-forge
+
+Install needed dependencies
+
+.. code-block::console
+ conda install noaa-gfdl::fre-cli
+ 
+setup.py file allows fre.py to be ran with fre as the entry point on the command line instead of python fre.py
+
+Enter commands and follow *--help* messages for guidance (brief rundown of commands also provided below)
+
+If the user just runs *fre*, it will list all the command groups following *fre*, such as *run*, *make*, *pp*, etc. and once the user specifies a command group, the list of available subcommands for that group will be shown
+
+Commands that require arguments to run will alert user about missing arguments, and will also list the rest of the optional parameters if *--help* is executed
+
+Argument flags are not positional, can be specified in any order as long as they are specified
+
+Can run directly from any directory, no need to clone repository
+
+May need to deactivate environment and reactivate it in order for changes to apply
+
+
+Tools
+-----
+
+A few subtools are currently in development:
+
+**fre pp**
+
+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*
+
+2. 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*
+
+
+**fre catalog**
+
+1. buildCatalog1
+* Builds json and csv format catalogs from user input directory path
+* Minimal Syntax: *fre catalog buildCatalog -i [input path] -o [output path]*
+* Module(s) needed: n/a
+* Example: *fre catalog buildCatalog -i /archive/am5/am5/am5f3b1r0/c96L65_am5f3b1r0_pdclim1850F/gfdl.ncrc5-deploy-prod-openmp/pp -o ~/output --overwrite*
+
+**To be developed:**
+
+#. fre check
+#. fre list
+#. fre make
+#. fre run
+#. fre test
+#. fre yamltools
+
+
+Usage (Developers)
+------------------
+
+Developers are free to use the user guide above to familiarize with the CLI and save time from having to install any dependencies, but development within a Conda environment is heavily recommended regardless
+
+Gain access to the repository with *git clone [email protected]:NOAA-GFDL/fre-cli.git* or your fork's link (recommended) and an SSH RSA key
+
+Once inside the repository, developers can test local changes by running a *pip install .* inside of the root directory to install the fre-cli package locally with the newest local changes
+
+Test as a normal user would use the CLI
+
+**Adding New Tools - Checklist**
+
+If there is *no* subdirectory created for the new tool you are trying to develop, there are a few steps to follow:
+
+1. Create a subdirectory for the tool group inside the /fre folder; i.e. /fre/fre(subTool)
+
+2. Add an *__init__.py* inside of the new subdirectory
+
+* This will contain one line, *from fre.fre(subTool) import **
+* The purpose of this line is to allow the subTool module to include all the scripts and functions within it when invoked by fre
+
+3. Add a file named *fre(subTool).py*. This will serve as the main file to house all of the tool's related subcommands
+
+4. Add a Click group named after the subTool within *fre(subTool).py*
+
+* This group will contain all of the subcommands
+
+5. Create separate files to house the code for each different subcommand; do not code out the full implemetation of a function inside of a Click command within *fre(subTool).py*
+
+6. Be sure to import the contents of the needed subcommand scripts inside of fre(subTool).py
+
+* i.e. from fre.fre(subTool).subCommandScript import *
+
+7. At this point, you can copy and paste the parts of your main Click subcommand from its script into *fre(subTool).py* when implementing the function reflective of the subcommand function
+
+* Everything will remain the same; i.e. arguments, options, etc.
+
+* However, this new function within *fre(subTool).py* must a new line after the arguments, options, and other command components; *@click.pass_context*
+
+* Along with this, a new argument "context" must now be added to the parameters of the command (preferably at the beginning, but it won't break it if it's not)
+
+8. From here, all that needs to be added after defining the command with a name is *context.forward(mainFunctionOfSubcommand)*, and done!
+
+9. After this step, it is important to add *from fre.fre(subTool) import* to the *__init__.py* within the /fre folder
+
+10. The last step is to replicate the subcommand in the same way as done in *fre(subTool).py* inside of *fre.py*, but make sure to add *from fre import fre(subTool)* and *from fre.fre(subTool).fre(subTool) import **
+
+Please refer to this issue when encountering naming issues: `NOAA-GFDL#31 <https://github.com/NOAA-GFDL/fre-cli/issues/31>`_
+
+**Adding Tools From Other Repositories**
+
+Currently, the solution to this task is to approach it using Conda packages. The tool that is being added must reside within a repository that contains a meta.yaml that includes Conda dependencies like the one in this repository and ideally a setup.py (may be subject to change due to deprecation) that may include any potentially needed pip dependencies
+
+* Once published as a Conda package, ideally on the NOAA-GFDL channel at https://anaconda.org/NOAA-GFDL, an addition can be made to the "run" section under the "requirements" category in the meta.yaml of the fre-cli following the syntax channel::package
+
+* On pushes to the main branch, the package located at https://anaconda.org/NOAA-GFDL/fre-cli will automatically be updated using the workflow file
+
+**MANIFEST.in**
+
+In the case where non-python files like templates, examples, and outputs are to be included in the fre-cli package, MANIFEST.in can provide the solution. Ensure that the file exists within the correct folder, and add a line to the MANIFEST.in file saying something like *include fre/fre(subTool)/fileName.fileExtension*
+
+* For more efficiency, if there are multiple files of the same type needed, the MANIFEST.in addition can be something like *recursive-include fre/fre(subTool) *.fileExtension* which would recursively include every file matching that fileExtension within the specified directory and its respective subdirectories.
+
+**Example /fre Directory Structure**
+.
+├── __init__.py
+├── fre.py
+├── fre(subTool)
+│   ├── __init__.py
+│   ├── subCommandScript.py
+│   └── fre(subTool).py