These tests should NOT fail

.github/workflows/build_conda.yml

@@ -9,11 +9,11 @@ jobs:
     container:
       image: continuumio/miniconda3:latest
     steps:
-    - name: Checkout Files
-      uses: actions/checkout@v4
-    - name: Run Docker to Build
-      run: |
-        conda config --append channels conda-forge
-        conda config --append channels noaa-gfdl
-        conda install conda-build conda-verify
-        conda build .
+      - name: Checkout Files
+        uses: actions/checkout@v4
+      - name: Run Conda to Build
+        run: |
+          conda config --append channels conda-forge
+          conda config --append channels noaa-gfdl
+          conda install conda-build conda-verify
+          conda build .

.github/workflows/create_test_conda_env.yml

@@ -7,42 +7,58 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '>=3.9'
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '>=3.9'
+
+      - name: Add conda to system path
+        run: |
+          # $CONDA is an env var pointing to root of miniconda dir
+          echo $CONDA/bin >> $GITHUB_PATH
+
+      - name: Create fre-cli environment
+        run: |
+          # create environment containing all dependencies
+          # the env cannot be explicitly activated in github CI/CD
+          conda env create -f environment.yml --name fre-cli
 
-    - name: Add conda to system path
-      run: |
-        # $CONDA is an environment variable pointing to the root of the miniconda directory
-        echo $CONDA/bin >> $GITHUB_PATH
+          # add conda env's executables to github's PATH equiv.
+          echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH
+
+          # use *conda environment's pip* to install fre-cli
+          # called w/ full path to conda's python for explicitness
+          # called as a module (-m pip) for explicitness
+          $CONDA/envs/fre-cli/bin/python -m pip install --prefix $CONDA/envs/fre-cli .
+
+      - name: Run pytest in fre-cli environment
+        run: |
+          # add conda env's executables to github's PATH equiv.
+          # does this need to be done twice?
+          echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH
 
-    - name: Create fre-cli environment
-      run: |
-        # create environment fre-cli will be installed into
-        conda env create -f environment.yml --name fre-cli
-        # try to make sure the right things are in GITHUB_PATH
-        echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH
-        # install fre-cli w pip
-        $CONDA/envs/fre-cli/bin/python -m pip install --prefix $CONDA/envs/fre-cli .
+          # are we talking to the right python?
+          which python
+          python --version
+          $CONDA/envs/fre-cli/bin/python --version
+
+          # run pytest, not explicitly from the conda env?
+          which pytest
+          pytest --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov=fre fre/
+
+      - name: Run pylint in fre-cli environment
+        run: |
+          # add conda env's executables to github's PATH equiv.
+          # does this need to be done a third time?
+          echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH
 
-    - name: Run pytest in fre-cli environment
-      run: |
-        # try to make sure the right things are in GITHUB_PATH
-        echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH
-        which python
-        python --version
-        $CONDA/envs/fre-cli/bin/python --version
-        # run pytest
-        pytest --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov=fre fre/
-
-    - name: Run pylint in fre-cli environment
-      run: |
-        # try to make sure the right things are in GITHUB_PATH
-        echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH
-        which python
-        python --version
-        $CONDA/envs/fre-cli/bin/python --version
-        # run pytest
-        pylint fre/ || echo "pylint returned non-zero exit code. preventing workflow from dying with this echo."
+          # are we talking to the right python?          
+          which python
+          python --version
+          $CONDA/envs/fre-cli/bin/python --version
+
+          # run pylint, not explicitly from the conda env?
+          which pylint
+          # ignore toothless complaint pylint has about netCDF4's stuff
+          pylint --ignored-modules netCDF4 fre/ || echo "pylint returned non-zero exit code. preventing workflow from dying with this echo."

.github/workflows/documentation.yml

@@ -17,6 +17,13 @@ jobs:
           pip install --upgrade sphinx-rtd-theme
       - name: Sphinx build
         run: |
+          # list content of docs dir before spinx-apidoc
+          ls docs/
+          # generate .rst from doc strings in fre/ modules
+          sphinx-apidoc --output-dir docs fre/ --separate          
+          # list content of docs dir after spinx-apidoc
+          ls docs/
+          # build content in docs/ dir, target is build/ dir
           sphinx-build docs build
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3

.github/workflows/publish_conda.yml

@@ -2,20 +2,20 @@ name: publish_conda
 on:
   push:
     branches:
-    - main
+      - main
 jobs:
   publish:
     runs-on: ubuntu-latest
     container:
       image: continuumio/miniconda3:latest
     steps:
-    - name: Checkout Files
-      uses: actions/checkout@v4
-    - name: Run Docker to Build and Upload
-      run: |
-        conda config --append channels conda-forge
-        conda config --append channels noaa-gfdl
-        conda install conda-build anaconda-client conda-verify
-        export ANACONDA_API_TOKEN=${{ secrets.ANACONDA_TOKEN }}
-        conda config --set anaconda_upload yes
-        conda build .
+      - name: Checkout Files
+        uses: actions/checkout@v4
+      - name: Run Conda to Build and Publish
+        run: |
+          conda config --append channels conda-forge
+          conda config --append channels noaa-gfdl
+          conda install conda-build anaconda-client conda-verify
+          export ANACONDA_API_TOKEN=${{ secrets.ANACONDA_TOKEN }}
+          conda config --set anaconda_upload yes
+          conda build .

docs/conf.py

@@ -14,7 +14,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = ['sphinx.ext.autodoc']
 
 templates_path = ['_templates']
 exclude_patterns = []

fre/README-tool-template.md → fre/README.md

@@ -1,3 +1,4 @@
+<!--
 # **[Tool Group Name]**
 _Brief description of tool group's purpose._
 
@@ -11,8 +12,12 @@ _Brief description of tool group's purpose._
 
 The [tool group] fre-cli tools are described below ([Subcommands](#subcommands)) as well as a Guide on the order in which to use them (Guide).
 
+
 ## **Usage (Users)**
-* Refer to fre-cli [README.md](https://github.com/NOAA-GFDL/fre-cli/blob/main/README.md) for foundational fre-cli usage guide and tips.
+-->
+* Refer to fre-cli [README.md](https://github.com/NOAA-GFDL/fre-cli/blob/main/README.md) for usage and tips.
+
+<!--
 * [tool group] package repository located at: _insert permalink_
 
 
@@ -35,3 +40,4 @@ fre [tool group] [subcommand] -[short/long command 1] [argument(s) 1] -[short/lo
 
 etc.
 ```
+-->

fre/app/__init__.py

@@ -1,4 +1,4 @@
-from .maskAtmosPlevel import maskAtmosPlevel_subtool
-from .freapp import appCli
+''' for fre.app imports '''
+from .freapp import app_cli
 
-__all__ = ["maskAtmosPlevel_subtool", "appCli"]
+__all__ = ["app_cli"]

fre/app/freapp.py

@@ -1,12 +1,19 @@
+#!/usr/bin/env python3
+''' fre app calls '''
+
+import time
+
 import click
-from .maskAtmosPlevel import maskAtmosPlevel_subtool
+
+from .mask_atmos_plevel import mask_atmos_plevel_subtool
 from .generate_time_averages.generate_time_averages import generate
 
 @click.group(help=click.style(" - access fre app subcommands", fg=(250,154,90)))
-def appCli():
-    pass
+def app_cli():
+    ''' entry point to fre app click commands '''
+
 
-@appCli.command()
+@app_cli.command()
 @click.option("-i", "--infile",
               type=str,
               help="Input NetCDF file containing pressure-level output to be masked",
@@ -20,11 +27,12 @@ def appCli():
               required=True)
 @click.pass_context
 def mask_atmos_plevel(context, infile, outfile, psfile):
+    # pylint: disable=unused-argument
     """Mask out pressure level diagnostic output below land surface"""
-    context.forward(maskAtmosPlevel_subtool)
+    context.forward(mask_atmos_plevel_subtool)
 
 
-@appCli.command()
+@app_cli.command()
 @click.option("-i", "--inf",
               type=str,
               required=True,
@@ -57,13 +65,15 @@ def mask_atmos_plevel(context, infile, outfile, psfile):
               help="Compute standard deviations for time-averages as well")
 @click.pass_context
 def gen_time_averages(context, inf, outf, pkg, var, unwgt, avg_type, stddev_type):
+    # pylint: disable=unused-argument
     """
-    generate time averages for specified set of netCDF files. Example: generate-time-averages.py /path/to/your/files/
+    generate time averages for specified set of netCDF files. 
+    Example: generate-time-averages.py /path/to/your/files/
     """
-    import time
     start_time=time.perf_counter()
     context.forward(generate)
-    print(f'Finished in total time {round(time.perf_counter() - start_time , 2)} second(s)') # need to change to a click.echo, not sure if echo supports f strings
+    # need to change to a click.echo, not sure if echo supports f strings
+    print(f'Finished in total time {round(time.perf_counter() - start_time , 2)} second(s)')
 
 if __name__ == "__main__":
-    appCli()
+    app_cli()