From 6999f4ce48eee2a660d85ddf97ecdbc8f39d0279 Mon Sep 17 00:00:00 2001 From: Ian <6273252+ilaflott@users.noreply.github.com> Date: Wed, 30 Oct 2024 14:10:06 -0400 Subject: [PATCH 01/29] Update create_test_conda_env.yml --- .github/workflows/create_test_conda_env.yml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index ce5de814..4ffacb43 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -16,7 +16,18 @@ jobs: run: | # $CONDA is an env var pointing to root of miniconda dir echo $CONDA/bin >> $GITHUB_PATH - + # info #1 + echo "----------------------------------------------------------------" + ls ~ + pwd + # info # 2 + echo "----------------------------------------------------------------" + mkdir ~/cylc-src + git clone https://github.com/noaa-gfdl/fre-workflows.git ~/cylc-src/FOO__BAR__BAZ + ls ~/cylc-src/FOO__BAR__BAZ + # done + echo "----------------------------------------------------------------" + - name: Create fre-cli environment run: | # create environment containing all dependencies From 9664af3860fd77f44ac80288324431e098ca8c29 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Tue, 5 Nov 2024 13:02:32 -0500 Subject: [PATCH 02/29] edit workflows to only build doc for this branch on my fork --- .github/workflows/build_conda.yml | 3 +- .github/workflows/create_test_conda_env.yml | 102 +++++++++----------- 2 files changed, 48 insertions(+), 57 deletions(-) diff --git a/.github/workflows/build_conda.yml b/.github/workflows/build_conda.yml index d9ba9162..692e43d9 100644 --- a/.github/workflows/build_conda.yml +++ b/.github/workflows/build_conda.yml @@ -2,7 +2,8 @@ name: build_conda on: pull_request: branches: - - main + - FOO +# - main jobs: build: runs-on: ubuntu-latest diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index 4ffacb43..70ebf468 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -16,63 +16,52 @@ jobs: run: | # $CONDA is an env var pointing to root of miniconda dir echo $CONDA/bin >> $GITHUB_PATH - # info #1 - echo "----------------------------------------------------------------" - ls ~ - pwd - # info # 2 - echo "----------------------------------------------------------------" - mkdir ~/cylc-src - git clone https://github.com/noaa-gfdl/fre-workflows.git ~/cylc-src/FOO__BAR__BAZ - ls ~/cylc-src/FOO__BAR__BAZ - # done - echo "----------------------------------------------------------------" - - 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 - - # 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: 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 +# +# # 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: | +# # try to make sure the right things are in GITHUB_PATH +# echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH +# +# # are we talking to the right python? +# 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 +# +# # are we talking to the right python? +# which python +# python --version +# $CONDA/envs/fre-cli/bin/python --version +# +# # run pylint, ignored modules avoid warnings arising from code internal to those modules +# pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code. preventing workflow from dying with this echo." - - 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 - - # are we talking to the right python? - 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 - - # are we talking to the right python? - which python - python --version - $CONDA/envs/fre-cli/bin/python --version - - # run pylint, ignored modules avoid warnings arising from code internal to those modules - pylint --max-args 6 -ry --ignored-modules netCDF4,cmor 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 @@ -82,7 +71,8 @@ jobs: - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.ref == 'refs/heads/main' }} + if: ${{ github.ref == 'refs/heads/update-fre-cmor-doc' }} +# if: ${{ github.ref == 'refs/heads/main' } with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} From 57071cd771936bd37733ea4210f7e3e78cce9849 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Tue, 5 Nov 2024 13:09:41 -0500 Subject: [PATCH 03/29] would be nice to have a sliiiightly faster doc turnaround... try using the conda packge installation method for now --- .github/workflows/create_test_conda_env.yml | 29 +++++++++++---------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index 70ebf468..767aa6ed 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -17,20 +17,21 @@ jobs: # $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 -# -# # 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: 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 + conda create -n fre-cli noaa-gfdl::fre-cli + + # 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: | # # try to make sure the right things are in GITHUB_PATH From 89a0e88f0756b18b0924364b555e204c313f7fbd Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Tue, 5 Nov 2024 13:12:00 -0500 Subject: [PATCH 04/29] ... why is conda-forge not part of default channels??? smh --- .github/workflows/create_test_conda_env.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index 767aa6ed..4bfa62af 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -22,6 +22,7 @@ jobs: # create environment containing all dependencies # the env cannot be explicitly activated in github CI/CD #conda env create -f environment.yml --name fre-cli + conda config --add channels conda-forge noaa-gfdl conda create -n fre-cli noaa-gfdl::fre-cli # add conda env's executables to github's PATH equiv. From 55668437ff4c6206da8e9374eb8e20996cfdf3c9 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Tue, 5 Nov 2024 13:12:47 -0500 Subject: [PATCH 05/29] *cries* --- .github/workflows/create_test_conda_env.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index 4bfa62af..37ea503a 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -22,7 +22,7 @@ jobs: # create environment containing all dependencies # the env cannot be explicitly activated in github CI/CD #conda env create -f environment.yml --name fre-cli - conda config --add channels conda-forge noaa-gfdl + conda config --add channels conda-forge noaa-gfdl conda create -n fre-cli noaa-gfdl::fre-cli # add conda env's executables to github's PATH equiv. From 8debc05f5de16ac337225c6d723f13754c2aa637 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Tue, 5 Nov 2024 13:14:03 -0500 Subject: [PATCH 06/29] *cries* more --- .github/workflows/create_test_conda_env.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index 37ea503a..b9c08f4d 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -22,7 +22,8 @@ jobs: # create environment containing all dependencies # the env cannot be explicitly activated in github CI/CD #conda env create -f environment.yml --name fre-cli - conda config --add channels conda-forge noaa-gfdl + conda config --add channels conda-forge + conda config --add channels noaa-gfdl conda create -n fre-cli noaa-gfdl::fre-cli # add conda env's executables to github's PATH equiv. From 7c405da77ee974f380a691f0a7ebd21e4a051e40 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Tue, 5 Nov 2024 13:27:14 -0500 Subject: [PATCH 07/29] ... can i strip out linting and test reqs for a simpler/hopefully slightly faster env build --- .github/workflows/create_test_conda_env.yml | 10 ++++----- environment.yml | 10 ++++----- meta.yaml | 24 ++++++++++----------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index b9c08f4d..226640c9 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -21,10 +21,10 @@ jobs: 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 - conda config --add channels conda-forge - conda config --add channels noaa-gfdl - conda create -n fre-cli noaa-gfdl::fre-cli + conda env create -f environment.yml --name fre-cli + #conda config --add channels conda-forge + #conda config --add channels noaa-gfdl + #conda create -n fre-cli noaa-gfdl::fre-cli # add conda env's executables to github's PATH equiv. echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH @@ -32,7 +32,7 @@ jobs: ## 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 . + $CONDA/envs/fre-cli/bin/python -m pip install --prefix $CONDA/envs/fre-cli . # - name: Run pytest in fre-cli environment # run: | diff --git a/environment.yml b/environment.yml index f1564558..83c577d5 100644 --- a/environment.yml +++ b/environment.yml @@ -8,7 +8,7 @@ dependencies: - pip - click - pyyaml - - pylint + # - pylint - jsonschema - noaa-gfdl::fre-nctools - noaa-gfdl::catalogbuilder @@ -18,9 +18,9 @@ dependencies: - conda-forge::metomi-rose - conda-forge::cmor - conda-forge::cylc-uiserver - - conda-forge::pytest - - conda-forge::pytest-cov + # - conda-forge::pytest + # - conda-forge::pytest-cov - conda-forge::python-cdo - conda-forge::cdo>=2.0.0 - - pip: - - GitPython + # - pip: + # - GitPython diff --git a/meta.yaml b/meta.yaml index 07f76686..9963e6cc 100644 --- a/meta.yaml +++ b/meta.yaml @@ -11,7 +11,7 @@ source: # git_url: https://github.com/NOAA-GFDL/fre-cli build: - script: + script: - {{ PYTHON }} -m pip install . -vv number: 1 noarch: python @@ -29,7 +29,7 @@ requirements: - python - click - pyyaml - - pylint + # - pylint - jsonschema - noaa-gfdl::catalogbuilder - noaa-gfdl::fre-nctools @@ -39,18 +39,18 @@ requirements: - conda-forge::metomi-rose - conda-forge::cmor - conda-forge::cylc-uiserver - - conda-forge::pytest - - conda-forge::pytest-cov + # - conda-forge::pytest + # - conda-forge::pytest-cov - conda-forge::python-cdo - conda-forge::cdo>=2.0.0 test: - source_files: + source_files: - fre/ imports: - click - - pytest - - pylint + # - pytest + # - pylint - fre - fre.pp - fre.pp.install @@ -62,8 +62,8 @@ test: - fre.cmor - fre.catalog commands: - - pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code and will kill the workflow. guarding against this now." - - pip install GitPython && pytest --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov=fre fre/ + # - pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code and will kill the workflow. guarding against this now." + # - pip install GitPython && pytest --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov=fre fre/ - fre --help - fre pp --help - fre pp install --help @@ -83,9 +83,9 @@ test: requires: - pip - - pylint - - pytest - - pytest-cov + # - pylint + # - pytest + # - pytest-cov about: home: https://github.com/NOAA-GFDL/fre-cli From 4b240f1ca230706b07d5b108247b28c61caf9466 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 11:45:06 -0500 Subject: [PATCH 08/29] update index, usage .rst files to start... why wont the code-block directives show? add backticks to calls in text bodies. --- docs/index.rst | 7 +++---- docs/usage.rst | 14 +++++++------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 77c46de6..5de5879d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,6 @@ -.. 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. +.. 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! =================================== diff --git a/docs/usage.rst b/docs/usage.rst index 95afbe5a..6d880678 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -19,21 +19,21 @@ Create new Conda environment Append necessary channels .. code-block::console - conda config --append channels noaa-gfdl - conda config --append channels conda-forge +conda config --append channels noaa-gfdl +conda config --append channels conda-forge Install needed dependencies .. code-block::console - conda install noaa-gfdl::fre-cli +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 +``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an **entry point**. Without it, the call would be, instead, ``python fre/fre.py`` -Enter commands and follow *--help* messages for guidance (brief rundown of commands also provided below) +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 +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 +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 From f9157ab4372abe6a32248716acb33c653e68cf68 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 11:47:13 -0500 Subject: [PATCH 09/29] try 4-space indent for code-block --- docs/usage.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 6d880678..384a24f6 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -19,13 +19,13 @@ Create new Conda environment Append necessary channels .. code-block::console -conda config --append channels noaa-gfdl -conda config --append channels conda-forge + conda config --append channels noaa-gfdl + conda config --append channels conda-forge Install needed dependencies .. code-block::console -conda install noaa-gfdl::fre-cli + conda install noaa-gfdl::fre-cli ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an **entry point**. Without it, the call would be, instead, ``python fre/fre.py`` From e7fb08813c917ef2090f2b507918b6a911541785 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 12:02:33 -0500 Subject: [PATCH 10/29] try breaking up long lines, other formatting things... code blocks still not showing?? --- docs/index.rst | 1 + docs/setup.rst | 18 +++++------ docs/usage.rst | 86 ++++++++++++++++++++++++++++---------------------- 3 files changed, 58 insertions(+), 47 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 5de5879d..1ae7bcbf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Welcome to Fre-Cli's documentation! setup usage subtools + contributing_to_doc FAQ badges diff --git a/docs/setup.rst b/docs/setup.rst index cf06bb99..49be8170 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -1,20 +1,20 @@ Setup ===== -Need to set up Conda environment first and foremost +Set up Conda environment first and foremost If on workstation: -module load conda +``module load conda`` -Create new Conda environment -conda create -n [environmentName] +Create new Conda environment: +``conda create -n [environmentName]`` -Append necessary channels -conda config --append channels noaa-gfdl -conda config --append channels conda-forge +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 +Run conda install on needed dependencies, should install the CLI package located at +https://anaconda.org/NOAA-GFDL/fre-cli : +``conda install noaa-gfdl::fre-cli`` 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 diff --git a/docs/usage.rst b/docs/usage.rst index 384a24f6..ac017da4 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -9,12 +9,12 @@ User Usage Load Conda .. code-block::console - module load conda + module load conda Create new Conda environment .. code-block::console - conda create -n [environmentName] + conda create -n [environmentName] Append necessary channels @@ -27,19 +27,13 @@ Install needed dependencies .. code-block::console conda install noaa-gfdl::fre-cli -``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an **entry point**. Without it, the call would be, instead, ``python fre/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 +* ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an **entry point**. Without it, the call would be, instead, ``python fre/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 @@ -52,25 +46,25 @@ A few subtools are currently in development: 1. configure * Postprocessing yaml configuration -* Minimal Syntax: *fre pp configure -y [user-edit yaml file]* +* 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* +* 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]* +* 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* +* 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]* +* 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* +* Example: ``fre catalog buildCatalog -i /archive/am5/am5/am5f3b1r0/c96L65_am5f3b1r0_pdclim1850F/gfdl.ncrc5-deploy-prod-openmp/pp -o ~/output --overwrite`` **To be developed:** @@ -85,52 +79,68 @@ A few subtools are currently in development: 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 +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 git@github.com:NOAA-GFDL/fre-cli.git* or your fork's link (recommended) and an SSH RSA key +Gain access to the repository with ``git clone git@github.com: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 +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 +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: +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 +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 +* 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 +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* +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 +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* +* 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) +* 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! +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 +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 ** +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 `_ +Please refer to this issue when encountering naming issues: +`NOAA-GFDL#31 `_ **Adding Tools From Other Repositories** From 295bfe64829470033fbe624c7beda4a31fd52515 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 12:20:48 -0500 Subject: [PATCH 11/29] actually add the contributing_to_doc file, edit usage file to include more subtools --- docs/contributing_to_doc.rst | 28 ++++++++++++++++++ docs/usage.rst | 55 ++++++++++++++++++------------------ 2 files changed, 55 insertions(+), 28 deletions(-) create mode 100644 docs/contributing_to_doc.rst diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst new file mode 100644 index 00000000..b5750457 --- /dev/null +++ b/docs/contributing_to_doc.rst @@ -0,0 +1,28 @@ +contributing_to_doc +================================================ + +How to Contribute to ``fre-cli``'s documentation +------------------------------------------------ + +* Fork fre-cli on github +* 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. +* Back on top where you found “settings”, find and click “actions” to the left +* Enable running the workflow actions assoc with the fre-cli repo under “.github/workflows” +* 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. +* 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). +* Ian’s is at https://ilaflott.github.io/ians_fre_cli/ +* 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 + + + diff --git a/docs/usage.rst b/docs/usage.rst index ac017da4..4d50f3b9 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -6,27 +6,11 @@ User Usage **Conda environment set up** -Load Conda +See "Setup". -.. code-block::console - module load conda -Create new Conda environment +**Calling ``fre``** -.. 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 - * ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an **entry point**. Without it, the call would be, instead, ``python fre/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 @@ -41,16 +25,38 @@ Tools A few subtools are currently in development: + +**fre app** + +1. ``generate-time-averages`` +2. ``regrid_xy`` + +**fre catalog** + +1. ``builder`` (out of date) +* 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`` + +**fre cmor** +1. ``run`` + + +**fre make** + **fre pp** -1. configure +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 +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]`` @@ -58,22 +64,15 @@ A few subtools are currently in development: * Example: ``fre pp checkout -e c96L65_am5f4b4r0_amip -p gfdl.ncrc5-deploy -t prod-openmp`` -**fre catalog** +**fre yamltools** -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) From 9c98f575532c38091086778314783bdffe43ee9c Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 12:37:26 -0500 Subject: [PATCH 12/29] one last attempt at code block, hyperlink noaa-gfdl conda channel --- docs/setup.rst | 2 +- docs/subtools.rst | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/setup.rst b/docs/setup.rst index 49be8170..71773d67 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -13,7 +13,7 @@ Append necessary channels: ``conda config --append channels noaa-gfdl; conda config --append channels conda-forge;`` Run conda install on needed dependencies, should install the CLI package located at -https://anaconda.org/NOAA-GFDL/fre-cli : +`the GFDL conda channel https://anaconda.org/NOAA-GFDL/fre-cli`_ : ``conda install noaa-gfdl::fre-cli`` All other dependencies used by the tools are installed along with this install (configured inside the meta.yaml), with the exception of local modules diff --git a/docs/subtools.rst b/docs/subtools.rst index ee6f663f..434e992d 100644 --- a/docs/subtools.rst +++ b/docs/subtools.rst @@ -28,7 +28,8 @@ Catalogs are generated by the following command: fre catalog buildcatalog Date: Wed, 6 Nov 2024 13:54:18 -0500 Subject: [PATCH 13/29] remove subtools.rst, too redundant with usage.rst. roughly update usage.rst. update index.rst accordingly. --- docs/index.rst | 1 - docs/setup.rst | 23 +++++++------------ docs/subtools.rst | 56 ----------------------------------------------- docs/usage.rst | 56 ++++++++++++++++++++++++++++++++--------------- 4 files changed, 46 insertions(+), 90 deletions(-) delete mode 100644 docs/subtools.rst diff --git a/docs/index.rst b/docs/index.rst index 1ae7bcbf..853b2f98 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,6 @@ Welcome to Fre-Cli's documentation! setup usage - subtools contributing_to_doc FAQ badges diff --git a/docs/setup.rst b/docs/setup.rst index 71773d67..07019f4e 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -1,32 +1,25 @@ Setup ===== -Set up Conda environment first and foremost +Set up Conda environment +------------------------ 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, should install the CLI package located at `the GFDL conda channel https://anaconda.org/NOAA-GFDL/fre-cli`_ : -``conda install noaa-gfdl::fre-cli`` - -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 +``conda install noaa-gfdl::fre-cli`` -May need to deactivate environment and reactivate it in order for changes to apply +* ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as + an **entry point**. Without it, the call would be, instead, ``python fre/fre.py`` diff --git a/docs/subtools.rst b/docs/subtools.rst deleted file mode 100644 index 434e992d..00000000 --- a/docs/subtools.rst +++ /dev/null @@ -1,56 +0,0 @@ -Subtools -======== - -fre app --------- - -fre catalog --------- - -The fre catalog tool brings the functionality of the `GFDL catalog builder `_ to fre users. The catalog builder is a python community package ecosystem that allows you to generate data catalogs compatible with intake-esm. - -**Subtools** - -Buildcatalog - Generate a data catalog - -Validate - Validate the catalog - -**Flags** - -Overwrite - Overwrite an existing catalog at the given output path - -Apend - Append (without headerlist) to an existing catalog at the given output path - -**Quickstart** - -Catalogs are generated by the following command: fre catalog buildcatalog - -(OUTPUT_PATH should end with the desired output filename WITHOUT a file ending) See example below. - -.. code-block:: console - - fre catalog buildcatalog --overwrite /archive/path_to_data_dir ~/output - -fre check (not yet implemented) --------- - -fre cmor --------- - -fre list (not yet implemented) --------- - -fre make --------- - -fre pp --------- - -fre run (not yet implemented) --------- - -fre test (not yet implemented) --------- - -fre yamltools --------- diff --git a/docs/usage.rst b/docs/usage.rst index 2083734b..51cef054 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -11,10 +11,14 @@ See "Setup". **Calling ``fre``** -* ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an **entry point**. Without it, the call would be, instead, ``python fre/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 +Brief rundown of commands also provided below: + +* Enter commands and follow ``--help`` messages for guidance +* 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 @@ -33,31 +37,34 @@ A few subtools are currently in development: **fre catalog** -1. ``builder`` (out of date) +1. ``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`` -2. ``validate`` +2. ``validate`` Validate the catalog + + **fre cmor** 1. ``run`` - +* placehold **fre make** +1. ``run-fremake`` +* placehold + **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 @@ -66,13 +73,16 @@ A few subtools are currently in development: **fre yamltools** +1. ``combine-yamls`` +* placehold + **To be developed:** -#. fre check -#. fre list -#. fre run -#. fre test +#. ``fre check`` +#. ``fre list`` +#. ``fre run`` +#. ``fre test`` Usage (Developers) @@ -144,17 +154,27 @@ Please refer to this issue when encountering naming issues: **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 +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 +* Once published as a Conda package, ideally on the `NOAA-GFDL conda channel`_, + 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 +* 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* +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. +* 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** . From 81237c1607714f74bc570de617faa6455d9b59d2 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 14:08:09 -0500 Subject: [PATCH 14/29] hey chan, i heard you like documentation. so i documentated the documentation in the documentation-documentation, so you can document your documenation while you document your documentation-documentation --- docs/contributing_to_doc.rst | 7 ++- docs/developer_usage.rst | 107 +++++++++++++++++++++++++++++++++++ docs/index.rst | 9 +-- docs/usage.rst | 99 -------------------------------- 4 files changed, 117 insertions(+), 105 deletions(-) create mode 100644 docs/developer_usage.rst diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst index b5750457..98b85085 100644 --- a/docs/contributing_to_doc.rst +++ b/docs/contributing_to_doc.rst @@ -1,5 +1,8 @@ -contributing_to_doc -================================================ +Documentation-Documentation +=========================== + +Welcome to `fre-cli`'s Documentation-documentation- where we document how the documentation is +documented How to Contribute to ``fre-cli``'s documentation ------------------------------------------------ diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst new file mode 100644 index 00000000..918333c5 --- /dev/null +++ b/docs/developer_usage.rst @@ -0,0 +1,107 @@ +Developer Usage +=============== + +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 git@github.com: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 `_ + +**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 conda channel`_, + 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 + +**Adding Documentation** +------------------------ +see section "Documentation-Documentation" diff --git a/docs/index.rst b/docs/index.rst index 853b2f98..2ceb962a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,11 +9,12 @@ Welcome to Fre-Cli's documentation! :maxdepth: 2 :caption: Contents: - setup - usage - contributing_to_doc + Setup + Usage + Developer Usage + Documentation Documentation FAQ - badges + Badges Indices and tables ================== diff --git a/docs/usage.rst b/docs/usage.rst index 51cef054..5a9a3023 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -85,102 +85,3 @@ A few subtools are currently in development: #. ``fre test`` -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 git@github.com: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 `_ - -**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 conda channel`_, - 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 From 7d619af4b4d91742a0788118fb7be26774be2526 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 14:33:43 -0500 Subject: [PATCH 15/29] remove FAQ.rst- empty. re-do table of contents, add proper restructuredtext headers to files- hopefully that makes the header names display right in the doc... one more trick totry after this ifthat doesnt owrk --- docs/FAQ.rst | 2 -- docs/badges.rst | 1 + docs/contributing_to_doc.rst | 3 +- docs/developer_usage.rst | 64 +++++++++++++++++++++--------------- docs/index.rst | 19 ++++++----- docs/setup.rst | 24 ++++++++------ 6 files changed, 64 insertions(+), 49 deletions(-) delete mode 100644 docs/FAQ.rst diff --git a/docs/FAQ.rst b/docs/FAQ.rst deleted file mode 100644 index cde88d85..00000000 --- a/docs/FAQ.rst +++ /dev/null @@ -1,2 +0,0 @@ -FAQ -=== diff --git a/docs/badges.rst b/docs/badges.rst index 542793d4..93fbb81b 100644 --- a/docs/badges.rst +++ b/docs/badges.rst @@ -1,3 +1,4 @@ +====== Badges ====== diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst index 98b85085..c05c4b67 100644 --- a/docs/contributing_to_doc.rst +++ b/docs/contributing_to_doc.rst @@ -1,3 +1,4 @@ +=========================== Documentation-Documentation =========================== @@ -5,7 +6,7 @@ Welcome to `fre-cli`'s Documentation-documentation- where we document how the do documented How to Contribute to ``fre-cli``'s documentation ------------------------------------------------- +================================================ * Fork fre-cli on github * On github, navigate to your fre-cli fork, and click “settings” diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index 918333c5..fbc4fb90 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -1,3 +1,4 @@ +=============== Developer Usage =============== @@ -5,18 +6,33 @@ Developers are free to use the user guide above to familiarize with the CLI and having to install any dependencies, but development within a Conda environment is heavily recommended regardless. - Gain access to the repository with ``git clone git@github.com:NOAA-GFDL/fre-cli.git`` or your fork's - link (recommended) and an SSH RSA key. + 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. -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** +==================== -**Adding New Tools - Checklist** --------------------------------- +**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 conda channel`_, + 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 + + + **Checklist** +-------------------------------- If there is *no* subdirectory created for the new tool you are trying to develop, there are a few steps to follow: @@ -66,20 +82,17 @@ steps to follow: Please refer to this issue when encountering naming issues: `NOAA-GFDL#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 +**Example /fre Directory Structure** +------------------------------------ -* Once published as a Conda package, ideally on the `NOAA-GFDL conda channel`_, - 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 +├── __init__.py +├── fre.py +├── fre(subTool) +│ ├── __init__.py +│ ├── subCommandScript.py +│ └── fre(subTool).py -* 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** --------------- @@ -92,16 +105,13 @@ MANIFEST.in file saying something like *include fre/fre(subTool)/fileName.fileEx 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 **Adding Documentation** ------------------------ see section "Documentation-Documentation" + + +**other note** +-------------- +``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an +**entry point**. Without it, the call would be, instead, ``python fre/fre.py`` diff --git a/docs/index.rst b/docs/index.rst index 2ceb962a..8eda1ba4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,8 @@ .. 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. + \`toctree\` directive (no backslashes) +=================================== Welcome to Fre-Cli's documentation! =================================== @@ -9,15 +10,15 @@ Welcome to Fre-Cli's documentation! :maxdepth: 2 :caption: Contents: - Setup - Usage - Developer Usage - Documentation Documentation - FAQ - Badges + setup + usage + developer_usage + contributing_to_doc + badges + -Indices and tables -================== +Indices +======= * :ref:`genindex` * :ref:`modindex` diff --git a/docs/setup.rst b/docs/setup.rst index 07019f4e..203f2341 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -1,25 +1,29 @@ +===== Setup ===== Set up Conda environment ------------------------- +======================== + +various options work quite well: -If on workstation: -``module load conda`` +If on workstation +----------------- -Create new Conda environment: +``module load fre/canopy`` + +Create new Conda environment +---------------------------- ``conda create -n [environmentName]`` -Append necessary channels: +activate: +``conda activate [environmentName]`` +append necessary channels: ``conda config --append channels noaa-gfdl; conda config --append channels conda-forge;`` -Run conda install on needed dependencies, should install the CLI package located at -`the GFDL conda channel https://anaconda.org/NOAA-GFDL/fre-cli`_ : - +install ``fre-cli`` into the activated environment from `the GFDL conda channel https://anaconda.org/NOAA-GFDL/fre-cli`_ : ``conda install noaa-gfdl::fre-cli`` -* ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as - an **entry point**. Without it, the call would be, instead, ``python fre/fre.py`` From 5569c3286642ee04843ce0bae1a6521869eab6e3 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 14:43:01 -0500 Subject: [PATCH 16/29] oooo i think i like this... --- docs/developer_usage.rst | 6 ++---- docs/usage.rst | 35 ++++++++++++++++++++++++----------- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index fbc4fb90..e8999563 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -111,7 +111,5 @@ MANIFEST.in file saying something like *include fre/fre(subTool)/fileName.fileEx see section "Documentation-Documentation" -**other note** --------------- -``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an -**entry point**. Without it, the call would be, instead, ``python fre/fre.py`` + + diff --git a/docs/usage.rst b/docs/usage.rst index 5a9a3023..2b52ed88 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,16 +1,12 @@ +===== Usage ===== -User Usage ----------- - -**Conda environment set up** - -See "Setup". +for setup, see the setup section. **Calling ``fre``** - +=================== Brief rundown of commands also provided below: * Enter commands and follow ``--help`` messages for guidance @@ -22,22 +18,27 @@ Brief rundown of commands also provided below: * 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 +* ``fre/setup.py`` allows ``fre/fre.py`` to be ran as ``fre`` on the command line by defining it as an + *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** +----------- 1. ``generate-time-averages`` 2. ``regrid_xy`` + **fre catalog** +--------------- 1. ``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 @@ -46,25 +47,34 @@ A few subtools are currently in development: 2. ``validate`` Validate the catalog - **fre cmor** +------------ + 1. ``run`` + * placehold + **fre make** +------------ 1. ``run-fremake`` + * placehold + **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 @@ -72,12 +82,15 @@ A few subtools are currently in development: **fre yamltools** +----------------- 1. ``combine-yamls`` + * placehold -**To be developed:** +**not-yet-implemented** +----------------------- #. ``fre check`` #. ``fre list`` From ef583f06906c2ed0cb799e7aecafaa87038f961f Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 15:27:42 -0500 Subject: [PATCH 17/29] improve formatting of current checklist in usage.rst and developer_usage.rst --- docs/developer_usage.rst | 111 ++++++++++++++++++++------------------- docs/usage.rst | 34 ++++++------ 2 files changed, 75 insertions(+), 70 deletions(-) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index e8999563..447a42da 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -7,107 +7,110 @@ having to install any dependencies, but development within a Conda environment i recommended regardless. Gain access to the repository with ``git clone git@github.com: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. +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** -==================== +Adding New Tools +================ -**From Other Repositories** +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) +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 conda channel`_, - 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 + an addition can be made to the "run" section under "requirements" in ``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 + be updated using by the workflow defined in ``.github/workflows/publish_conda.yml`` - **Checklist** --------------------------------- -If there is *no* subdirectory created for the new tool you are trying to develop, there are a few -steps to follow: +Checklist +--------- + +For the new tool you are trying to develop, there are a few criteria to satisfy -1. Create a subdirectory for the tool group inside the /fre folder; i.e. /fre/fre(subTool) +1. Create a subdirectory for the tool group inside the ``fre/`` directory; i.e. ``fre/`` -2. Add an ``__init__.py`` inside of the new subdirectory +2. Add an ``__init__.py`` inside of ``fre/`` -* 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 +* typically this file should be empty, but it depends on the ````'s needs +* even if empty, the file facillitates module importability and must be present -3. Add a file named *fre(subTool).py*. This will serve as the main file to house all of the tool's - related subcommands +3. Add a file named ``fre//fre.py``. This will serve as the main entry point for ``fre`` + into the ````'s functionality -4. Add a Click group named after the subTool within *fre(subTool).py* +4. Add a ``click`` group named after ```` within ``fre//fre.py`` -* This group will contain all of the subcommands +* This ``click`` group will contain all the subcommands under the ````'s functionality -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* +5. Create separate files as needed for different subcommands; do not code out the full + implemetation of ```` inside of a ``click`` command within ``fre//fre.py``. -6. Be sure to import the contents of the needed subcommand scripts inside of fre(subTool).py +* better yet, consider what structure your subtool may need in the future for maintainability's sake -* i.e. from fre.fre(subTool).subCommandScript import * +6. Be sure to import the contents of the needed subcommand scripts inside of ``fre.py`` -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 +* i.e. from ``fre.fre.subCommandScript import *`` + +7. At this point, you can copy and paste the parts of your main ``click`` subcommand from its script + into ``fre.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* +* However, this new function within ``fre.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 +* 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! + ``context.forward(mainFunctionOfSubcommand)``, and done! -9. After this step, it is important to add *from fre.fre(subTool) import* to the *__init__.py* +9. After this step, it is important to add ``from fre.fre import`` to ``__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 ** +10. The last step is to replicate the subcommand in the same way as done in ``fre.py`` + inside of ``fre.py``, but make sure to add ``from fre import fre`` and + ``from fre.fre.fre import *`` Please refer to this issue when encountering naming issues: `NOAA-GFDL#31 `_ -**Example /fre Directory Structure** ------------------------------------- +Example ``fre/`` Directory Structure +-------------------------------- -├── __init__.py -├── fre.py -├── fre(subTool) -│ ├── __init__.py -│ ├── subCommandScript.py -│ └── fre(subTool).py +├── ``__init__.py`` +├── ``fre.py`` +├── ``fre`` +│ ├── ``__init__.py`` +│ ├── ``subCommandScript.py`` +│ └── ``fre.py`` -**MANIFEST.in** +``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* +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/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 *.fileExtension`` which would recursively include every file matching that + ``fileExtension`` within the specified directory and its respective subdirectories. -* 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. +Adding Documentation +-------------------- -**Adding Documentation** ------------------------- see section "Documentation-Documentation" diff --git a/docs/usage.rst b/docs/usage.rst index 2b52ed88..0a7a0399 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -5,8 +5,9 @@ Usage for setup, see the setup section. -**Calling ``fre``** -=================== +Calling ``fre`` +=============== + Brief rundown of commands also provided below: * Enter commands and follow ``--help`` messages for guidance @@ -24,18 +25,19 @@ Brief rundown of commands also provided below: Tools ===== + A few subtools are currently in development: -**fre app** ------------ +fre app +------- 1. ``generate-time-averages`` 2. ``regrid_xy`` -**fre catalog** ---------------- +fre catalog +----------- 1. ``builder`` Generate a catalog @@ -47,24 +49,24 @@ A few subtools are currently in development: 2. ``validate`` Validate the catalog -**fre cmor** ------------- +fre cmor +-------- 1. ``run`` * placehold -**fre make** ------------- +fre make +-------- 1. ``run-fremake`` * placehold -**fre pp** ----------- +fre pp +------ 1. ``configure`` @@ -81,16 +83,16 @@ A few subtools are currently in development: * Example: ``fre pp checkout -e c96L65_am5f4b4r0_amip -p gfdl.ncrc5-deploy -t prod-openmp`` -**fre yamltools** ------------------ +fre yamltools +------------- 1. ``combine-yamls`` * placehold -**not-yet-implemented** ------------------------ +not-yet-implemented +------------------- #. ``fre check`` #. ``fre list`` From 9e4e0510d2988d8dcc167e3dc82a22dd3fd1a2db Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 15:30:20 -0500 Subject: [PATCH 18/29] toc depth and a minor thingy here and there --- docs/developer_usage.rst | 8 ++++---- docs/index.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index 447a42da..455ae73b 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -17,15 +17,15 @@ Adding New 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 +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 conda channel`_, - an addition can be made to the "run" section under "requirements" in ``meta.yaml`` of the ``fre-cli`` + an addition can be made to the ``run`` section under ``requirements`` in ``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 @@ -86,7 +86,7 @@ Please refer to this issue when encountering naming issues: Example ``fre/`` Directory Structure --------------------------------- +------------------------------------ ├── ``__init__.py`` ├── ``fre.py`` diff --git a/docs/index.rst b/docs/index.rst index 8eda1ba4..111c8302 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,7 @@ Welcome to Fre-Cli's documentation! =================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: setup From ee23c7ffa2c6e9fa3b1216e09dd80eb5c0f6b997 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 15:47:01 -0500 Subject: [PATCH 19/29] try to fix directory tree example --- docs/developer_usage.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index 455ae73b..ac5c0148 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -88,6 +88,7 @@ Please refer to this issue when encountering naming issues: Example ``fre/`` Directory Structure ------------------------------------ +``fre/`` ├── ``__init__.py`` ├── ``fre.py`` ├── ``fre`` From 3e33828e897079f96e36f01e96b85c116cd4a6ff Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 15:51:16 -0500 Subject: [PATCH 20/29] fix noaa-gfdl conda channel link text, make doc-doc text easier to read --- docs/contributing_to_doc.rst | 34 +++++++++++++++++++++------------- docs/developer_usage.rst | 2 +- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst index c05c4b67..7093fc77 100644 --- a/docs/contributing_to_doc.rst +++ b/docs/contributing_to_doc.rst @@ -2,31 +2,39 @@ Documentation-Documentation =========================== -Welcome to `fre-cli`'s Documentation-documentation- where we document how the documentation is +Welcome to ``fre-cli``'s Documentation-documentation- where we document how the documentation is documented How to Contribute to ``fre-cli``'s documentation ================================================ -* Fork fre-cli on github -* On github, navigate to your fre-cli fork, and click “settings” + + +1. fork and poke at the settings +* Fork ``fre-cli`` on github +* 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, +* 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 * Back on top where you found “settings”, find and click “actions” to the left -* Enable running the workflow actions assoc with the fre-cli repo under “.github/workflows” -* 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 +* Enable running the workflow actions assoc with the ``fre-cli`` repo under ``.github/workflows`` + + +3. run your forks 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 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). -* Ian’s is at https://ilaflott.github.io/ians_fre_cli/ + 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 index ac5c0148..ea27501d 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -24,7 +24,7 @@ added must reside within a repository that contains a ``meta.yaml`` that include 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 conda channel`_, +* Once published as a Conda package, ideally on the `NOAA-GFDL conda channel `_, an addition can be made to the ``run`` section under ``requirements`` in ``meta.yaml`` of the ``fre-cli`` following the syntax ``channel::package`` From a14c1e75e4c092f4ae36dc39d6d3249cc95f89fe Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 16:01:02 -0500 Subject: [PATCH 21/29] put other files back the way they were! --- .github/workflows/build_conda.yml | 3 +- .github/workflows/create_test_conda_env.yml | 66 ++++++++++----------- environment.yml | 10 ++-- meta.yaml | 20 +++---- 4 files changed, 47 insertions(+), 52 deletions(-) diff --git a/.github/workflows/build_conda.yml b/.github/workflows/build_conda.yml index 882180d3..e11fb93d 100644 --- a/.github/workflows/build_conda.yml +++ b/.github/workflows/build_conda.yml @@ -2,8 +2,7 @@ name: build_conda on: pull_request: branches: - - FOO -# - main + - main jobs: build: runs-on: ubuntu-latest diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index 57e4f829..b6044586 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -23,9 +23,6 @@ jobs: # create environment containing all dependencies # the env cannot be explicitly activated in github CI/CD conda env create -f environment.yml --name fre-cli - #conda config --add channels conda-forge - #conda config --add channels noaa-gfdl - #conda create -n fre-cli noaa-gfdl::fre-cli # add conda env's executables to github's PATH equiv. echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH @@ -35,36 +32,36 @@ jobs: ## 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: | -# # try to make sure the right things are in GITHUB_PATH -# echo $CONDA/envs/fre-cli/bin >> $GITHUB_PATH -# -# # are we talking to the right python? -# 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 -# -# # are we talking to the right python? -# which python -# python --version -# $CONDA/envs/fre-cli/bin/python --version -# -# # run pylint, ignored modules avoid warnings arising from code internal to those modules -# pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code. preventing workflow from dying with this echo." + - 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 + + # are we talking to the right python? + 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 + + # are we talking to the right python? + which python + python --version + $CONDA/envs/fre-cli/bin/python --version + + # run pylint, ignored modules avoid warnings arising from code internal to those modules + pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code. preventing workflow from dying with this echo." - name: Install Sphinx and Build Documentation run: | @@ -75,8 +72,7 @@ jobs: - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.ref == 'refs/heads/update-fre-cmor-doc' }} -# if: ${{ github.ref == 'refs/heads/main' } + if: ${{ github.ref == 'refs/heads/main' } with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/environment.yml b/environment.yml index 83c577d5..f1564558 100644 --- a/environment.yml +++ b/environment.yml @@ -8,7 +8,7 @@ dependencies: - pip - click - pyyaml - # - pylint + - pylint - jsonschema - noaa-gfdl::fre-nctools - noaa-gfdl::catalogbuilder @@ -18,9 +18,9 @@ dependencies: - conda-forge::metomi-rose - conda-forge::cmor - conda-forge::cylc-uiserver - # - conda-forge::pytest - # - conda-forge::pytest-cov + - conda-forge::pytest + - conda-forge::pytest-cov - conda-forge::python-cdo - conda-forge::cdo>=2.0.0 - # - pip: - # - GitPython + - pip: + - GitPython diff --git a/meta.yaml b/meta.yaml index 5c7574fc..246de2a1 100644 --- a/meta.yaml +++ b/meta.yaml @@ -29,7 +29,7 @@ requirements: - python - click - pyyaml - # - pylint + - pylint - jsonschema - noaa-gfdl::catalogbuilder - noaa-gfdl::fre-nctools @@ -39,8 +39,8 @@ requirements: - conda-forge::metomi-rose - conda-forge::cmor - conda-forge::cylc-uiserver - # - conda-forge::pytest - # - conda-forge::pytest-cov + - conda-forge::pytest + - conda-forge::pytest-cov - conda-forge::python-cdo - conda-forge::cdo>=2.0.0 @@ -49,8 +49,8 @@ test: - fre/ imports: - click - # - pytest - # - pylint + - pytest + - pylint - fre - fre.pp - fre.pp.install @@ -62,8 +62,8 @@ test: - fre.cmor - fre.catalog commands: - # - pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code and will kill the workflow. guarding against this now." - # - pip install GitPython && pytest --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov=fre fre/ + - pylint --max-args 6 -ry --ignored-modules netCDF4,cmor fre/ || echo "pylint returned non-zero exit code and will kill the workflow. guarding against this now." + - pip install GitPython && pytest --config-file=fre/pytest.ini --cov-config=fre/coveragerc --cov=fre fre/ - fre --help - fre pp --help - fre pp install --help @@ -83,9 +83,9 @@ test: requires: - pip - # - pylint - # - pytest - # - pytest-cov + - pylint + - pytest + - pytest-cov about: home: https://github.com/NOAA-GFDL/fre-cli From 6375e2b63fadf1f20318d34eb3720197e4014000 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 16:01:41 -0500 Subject: [PATCH 22/29] syntax mistake in workflow file --- .github/workflows/create_test_conda_env.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/create_test_conda_env.yml b/.github/workflows/create_test_conda_env.yml index b6044586..d04398bd 100644 --- a/.github/workflows/create_test_conda_env.yml +++ b/.github/workflows/create_test_conda_env.yml @@ -72,7 +72,7 @@ jobs: - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.ref == 'refs/heads/main' } + if: ${{ github.ref == 'refs/heads/main' }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} From fd815229cc62c9d5eca55b99e480e3d9ead7df13 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 16:04:09 -0500 Subject: [PATCH 23/29] add more specific warning in doc-doc instructions --- docs/contributing_to_doc.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst index 7093fc77..cf4b524e 100644 --- a/docs/contributing_to_doc.rst +++ b/docs/contributing_to_doc.rst @@ -20,7 +20,8 @@ How to Contribute to ``fre-cli``'s documentation nor interact with anything in that branch directly. -2. enable workflows for your fork +2. enable workflows for your fork +* note: this step may depend on user-specific settings! * Back on top where you found “settings”, find and click “actions” to the left * Enable running the workflow actions assoc with the ``fre-cli`` repo under ``.github/workflows`` From b1e896b2c9dd54d2b6c3c08b9c5f6bd9dcf931bb Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 16:10:27 -0500 Subject: [PATCH 24/29] try diff doc-doc indent --- docs/contributing_to_doc.rst | 41 +++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/contributing_to_doc.rst b/docs/contributing_to_doc.rst index cf4b524e..edaf8476 100644 --- a/docs/contributing_to_doc.rst +++ b/docs/contributing_to_doc.rst @@ -11,31 +11,34 @@ How to Contribute to ``fre-cli``'s documentation 1. fork and poke at the settings -* Fork ``fre-cli`` on github -* 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. + + * Fork ``fre-cli`` on github + * 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. 2. enable workflows for your fork -* note: this step may depend on user-specific settings! -* Back on top where you found “settings”, find and click “actions” to the left -* Enable running the workflow actions assoc with the ``fre-cli`` repo under ``.github/workflows`` + + * note: this step may depend on user-specific settings! + * Back on top where you found “settings”, find and click “actions” to the left + * Enable running the workflow actions assoc with the ``fre-cli`` repo under ``.github/workflows`` 3. run your forks 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 - so that it runs when you push to any branch, and make a small, trivial, commit somewhere to your - 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). -* 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 + + * 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. + * 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). + * 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 From c239d3d278d6637867171fb519a01a5ec51f07e4 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 17:19:08 -0500 Subject: [PATCH 25/29] dana/ryan PR feedback TO THE CORRECT BRANCH --- docs/developer_usage.rst | 52 +++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index ea27501d..a74f8243 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -37,49 +37,51 @@ Checklist For the new tool you are trying to develop, there are a few criteria to satisfy -1. Create a subdirectory for the tool group inside the ``fre/`` directory; i.e. ``fre/`` +1. Create a subdirectory for the tool group inside the ``fre/`` directory; i.e. ``fre/`` -2. Add an ``__init__.py`` inside of ``fre/`` +2. Add an ``__init__.py`` inside of ``fre/`` -* typically this file should be empty, but it depends on the ````'s needs +* typically this file should be empty, but it depends on the ````'s needs * even if empty, the file facillitates module importability and must be present -3. Add a file named ``fre//fre.py``. This will serve as the main entry point for ``fre`` - into the ````'s functionality +3. Add a file named ``fre//fre.py``. This will serve as the main entry point for ``fre`` + into the ````'s functionality -4. Add a ``click`` group named after ```` within ``fre//fre.py`` +4. Add a ``click`` group named after ```` within ``fre//fre.py`` -* This ``click`` group will contain all the subcommands under the ````'s functionality +* This ``click`` group will contain all the functionality under the ```` -5. Create separate files as needed for different subcommands; do not code out the full - implemetation of ```` inside of a ``click`` command within ``fre//fre.py``. +5. Create separate files as needed for different commands; do not code out the full + implemetation of ```` inside of a ``click`` command within ``fre//fre.py``. -* better yet, consider what structure your subtool may need in the future for maintainability's sake +* better yet, consider what structure your tool may need in the future for maintainability's sake +* if you need, specify a ```` like ``fre//``. ``fre/app`` currently has + this structure -6. Be sure to import the contents of the needed subcommand scripts inside of ``fre.py`` +6. Be sure to import the contents of the needed subcommand scripts inside of ``fre.py`` -* i.e. from ``fre.fre.subCommandScript import *`` +* i.e. from ``fre.fre.toolCommandScript import *`` -7. At this point, you can copy and paste the parts of your main ``click`` subcommand from its script - into ``fre.py`` when implementing the function reflective of the subcommand function +7. At this point, you can copy and paste the parts of your main ``click`` command from its script + into ``fre.py`` when implementing the function reflective of the command function * Everything will remain the same; i.e. arguments, options, etc. -* However, this new function within ``fre.py`` must a new line after the arguments, options, +* However, this new function within ``fre.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! + ``context.forward(mainFunctionOfToolCommand)``, and done! -9. After this step, it is important to add ``from fre.fre import`` to ``__init__.py`` +9. After this step, it is important to add ``from fre.fre import`` to ``__init__.py`` within the /fre folder -10. The last step is to replicate the subcommand in the same way as done in ``fre.py`` - inside of ``fre.py``, but make sure to add ``from fre import fre`` and - ``from fre.fre.fre import *`` +10. The last step is to replicate the command in the same way as done in ``fre.py`` + inside of ``fre.py``, but make sure to add ``from fre import fre`` and + ``from fre.fre.fre import *`` Please refer to this issue when encountering naming issues: `NOAA-GFDL#31 `_ @@ -91,10 +93,10 @@ Example ``fre/`` Directory Structure ``fre/`` ├── ``__init__.py`` ├── ``fre.py`` -├── ``fre`` +├── ``fre`` │ ├── ``__init__.py`` -│ ├── ``subCommandScript.py`` -│ └── ``fre.py`` +│ ├── ``toolCommandScript.py`` +│ └── ``fre.py`` ``MANIFEST.in`` @@ -102,10 +104,10 @@ Example ``fre/`` Directory Structure 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/fileName.fileExtension`` +``MANIFEST.in`` file saying something like ``include fre/fre/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 *.fileExtension`` which would recursively include every file matching that + like ``recursive-include fre/fre *.fileExtension`` which would recursively include every file matching that ``fileExtension`` within the specified directory and its respective subdirectories. From 9dc247bd17804e1835652ea4fa62c2d11f44b272 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 17:22:02 -0500 Subject: [PATCH 26/29] more dana feedback for PR --- docs/developer_usage.rst | 2 +- docs/setup.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index a74f8243..6bc5fa8b 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -6,7 +6,7 @@ Developers are free to use the user guide above to familiarize with the CLI and having to install any dependencies, but development within a Conda environment is heavily recommended regardless. -Gain access to the repository with ``git clone git@github.com:NOAA-GFDL/fre-cli.git`` or your fork's +Gain access to the repository with ``git clone --recursive git@github.com: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. diff --git a/docs/setup.rst b/docs/setup.rst index 203f2341..e613aaa6 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -11,7 +11,7 @@ various options work quite well: If on workstation ----------------- -``module load fre/canopy`` +``module load fre/2024.01`` Create new Conda environment From 4be206f5cd3283fa74a056b518b7039ee59f9c89 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 17:23:44 -0500 Subject: [PATCH 27/29] last bit of dana feedback- others to add gaea things! --- docs/setup.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/setup.rst b/docs/setup.rst index e613aaa6..64fa23f3 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -16,9 +16,14 @@ If on workstation Create new Conda environment ---------------------------- + +if you're at GFDL: +``module load miniforge`` + +create an empty environment to start ``conda create -n [environmentName]`` -activate: +activate the empty environment: ``conda activate [environmentName]`` append necessary channels: From 1aaa3255516eff3e843f2038251794c60d70186c Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 18:20:41 -0500 Subject: [PATCH 28/29] capital --- docs/setup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup.rst b/docs/setup.rst index 64fa23f3..7dfd1492 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -14,7 +14,7 @@ If on workstation ``module load fre/2024.01`` -Create new Conda environment +Create New Conda environment ---------------------------- if you're at GFDL: From d2c51a954815c60cc578aed7dea7294209fcdcf7 Mon Sep 17 00:00:00 2001 From: Ian Laflotte Date: Wed, 6 Nov 2024 18:27:44 -0500 Subject: [PATCH 29/29] PR feedback --- docs/developer_usage.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/developer_usage.rst b/docs/developer_usage.rst index 6bc5fa8b..7ab3376f 100644 --- a/docs/developer_usage.rst +++ b/docs/developer_usage.rst @@ -60,7 +60,7 @@ For the new tool you are trying to develop, there are a few criteria to satisfy 6. Be sure to import the contents of the needed subcommand scripts inside of ``fre.py`` -* i.e. from ``fre.fre.toolCommandScript import *`` +* i.e. from ``fre..toolCommandScript import *`` 7. At this point, you can copy and paste the parts of your main ``click`` command from its script into ``fre.py`` when implementing the function reflective of the command function @@ -76,12 +76,9 @@ For the new tool you are trying to develop, there are a few criteria to satisfy 8. From here, all that needs to be added after defining the command with a name is ``context.forward(mainFunctionOfToolCommand)``, and done! -9. After this step, it is important to add ``from fre.fre import`` to ``__init__.py`` - within the /fre folder - -10. The last step is to replicate the command in the same way as done in ``fre.py`` - inside of ``fre.py``, but make sure to add ``from fre import fre`` and - ``from fre.fre.fre import *`` +9. The last step is to replicate the command in the same way as done in ``fre.py`` + inside of ``fre.py``, but make sure to add ``from fre import `` and + ``from fre. import *`` Please refer to this issue when encountering naming issues: `NOAA-GFDL#31 `_