#161 Merge branch 'main' of github.com:NOAA-GFDL/fre-cli into 161.cr…

…eate-combine-yaml-tool
NOAA-GFDL · Aug 21, 2024 · e015052 · e015052
2 parents 5bfc8c1 + 18719f7
commit e015052
Show file tree

Hide file tree

Showing 68 changed files with 888 additions and 638 deletions.
diff --git a/.github/workflows/build_conda.yml b/.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 .
diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml
@@ -5,44 +5,89 @@ on: [push]
 jobs:
   build-linux:
     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 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 --junit-xml=pytest_results.xml --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov-report=xml --cov=fre fre/
+          # install genbadge to generate coverage badge based on xml
+          pip install genbadge
+          genbadge coverage -v -i coverage.xml -o docs/cov_badge.svg
+          genbadge tests -v -i pytest_results.xml -o docs/pytest_badge.svg
+        
+      - 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 pylint
+          pylint fre/ || echo "pylint returned non-zero exit code. preventing workflow from dying with this echo."
+      
+      - name: Install Sphinx and Build Documentation
+        run: |
+          pip install sphinx renku-sphinx-theme sphinx-rtd-theme          
+          pip install --upgrade sphinx-rtd-theme
+          sphinx-apidoc --output-dir docs fre/ --separate
+          sphinx-build docs build
 
-    - 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."
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build/
+          force_orphan: true
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
diff --git a/.github/workflows/publish_conda.yml b/.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 .
diff --git a/README.md b/README.md
@@ -1,14 +1,22 @@
+<!-- from https://anaconda.org/NOAA-GFDL/fre-cli/badges -->
+[![Anaconda-Server Badge](https://anaconda.org/noaa-gfdl/fre-cli/badges/version.svg)](https://anaconda.org/noaa-gfdl/fre-cli)
+[![Anaconda-Server Badge](https://anaconda.org/noaa-gfdl/fre-cli/badges/latest_release_date.svg)](https://anaconda.org/noaa-gfdl/fre-cli)
+[![Anaconda-Server Badge](https://anaconda.org/noaa-gfdl/fre-cli/badges/latest_release_relative_date.svg)](https://anaconda.org/noaa-gfdl/fre-cli)
+[![CI](https://github.com/NOAA-GFDL/fre-cli/workflows/publish_conda/badge.svg)](https://github.com/NOAA-GFDL/fre-cli/actions?query=workflow%3Apublish_conda+branch%3Amain++)
+![Coverage Badge](https://noaa-gfdl.github.io/fre-cli/_images/cov_badge.svg)
+![Pytest Badge](https://noaa-gfdl.github.io/fre-cli/_images/pytest_badge.svg)
+
 # **FRE-CLI**
 
 FMS Runtime Environment (FRE) CLI developed using Python's Click package
 
-* [Sphinx Page](https://noaa-gfdl.github.io/fre-cli/index.html)
-* [Project Outline](https://docs.google.com/document/d/19Uc01IPuuIuMtOyAvxXj9Mn6Ivc5Ql6NZ-Q6I8YowRI/edit?usp=sharing)
+* [Sphinx Documentation](https://noaa-gfdl.github.io/fre-cli/index.html)
+<!--* ... internal doc, should remove, if anything...
+[Project Outline](https://docs.google.com/document/d/19Uc01IPuuIuMtOyAvxXj9Mn6Ivc5Ql6NZ-Q6I8YowRI/edit?usp=sharing) -->
 
 ![IMG_1076](https://github.com/NOAA-GFDL/fre-cli/assets/98476720/817cabe1-6e3b-4210-9874-b13f601265d6)
 
 ## **Background**
-
 `fre-cli` is a modern, user-friendly CLI that will allow users to call FRE commands using a **_fre_** **tool** _subtool_ syntax. Leveraging Click, an easily installable Python package available via PyPI and/or Conda, `fre-cli` gives users intuitive and easy-to-understand access to many FRE tools and workflows from one packaged, centralized CLI.
 
 ![Screenshot from 2024-04-18 13-42-04](https://github.com/NOAA-GFDL/fre-cli/assets/98476720/43c028a6-4e6a-42fe-8bec-008b6758ea9b)

diff --git a/docs/badges.rst b/docs/badges.rst
@@ -0,0 +1,5 @@
+Badges
+======
+
+.. image:: cov_badge.svg
+.. image:: pytest_badge.svg
diff --git a/docs/conf.py b/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 = []

diff --git a/docs/index.rst b/docs/index.rst
@@ -14,6 +14,7 @@ Welcome to Fre-Cli's documentation!
    usage
    subtools
    FAQ
+   badges
 
 Indices and tables
 ==================

diff --git a/fre/README-tool-template.md → fre/README.md b/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.
 ```
+-->
diff --git a/fre/app/__init__.py b/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"]
diff --git a/fre/app/freapp.py b/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()