cmor tool improvements

[ilaflott]

• I ran my code
• I tried to make my code readable
• I tried to comment my code
• I wrote a new test, if applicable
• I wrote new instructions/documentation, if applicable
• I ran pytest and inspected it's output
• I ran pylint and attempted to implement some of it's feedback

This PR...

• overhauls the README.md with fre-cli oriented usage and removes outdated doc
• refactors cmor_mixer.py heavily to be more readable, have more modularity to it to clearly illustrate who-does-what and why, with an emphasis on clearly exposing data movement inherent in the routine
• functions now have doc strings with argument descriptions in most places
• better run-time feedback of functioning/IO/logic etc during runtime, hopefully not too much
• better comments where possible
• new test case where key:value pair in var_list argument differ
• more test case cleanup/setup, more specific test case success conditions
• new CLI/click.testing.CliRunner test for the new functionality of the fre.cmor module
• change of the way the click module interfaces with the cmor run subtool module

[ilaflott]

these cleanup steps throw some very annoying error messages if you don't let the exception go-

...
...
...
fre/cmor/tests/test_cmor_run_subtool.py::test_fre_cmor_run_subtool_case1_output_compare_metadata PASSED                                                                            [ 55%]
fre/cmor/tests/test_cmor_run_subtool.py::test_setup_fre_cmor_run_subtool_case2 FAILED                                                                                              [ 66%]

======================================================================================== FAILURES ========================================================================================
_________________________________________________________________________ test_setup_fre_cmor_run_subtool_case2 __________________________________________________________________________

capfd = <_pytest.capture.CaptureFixture object at 0x2b0f0acad790>

    def test_setup_fre_cmor_run_subtool_case2(capfd):
        ''' make a copy of the input file to the slightly different name.
        checks for outputfile from prev pytest runs, removes it if it's present.
        this routine also checks to make sure the desired input file is present'''
        if Path(FULL_OUTPUTFILE).exists():
            Path(FULL_OUTPUTFILE).unlink()
        assert not Path(FULL_OUTPUTFILE).exists()
    
        if Path(OUTDIR+'/CMIP6').exists():
            shutil.rmtree(OUTDIR+'/CMIP6')
        assert not Path(OUTDIR+'/CMIP6').exists()
    
    
        # VERY ANNOYING !!! FYI WARNING TODO
        if Path(TMPDIR).exists():
            #try:
>           shutil.rmtree(TMPDIR)

fre/cmor/tests/test_cmor_run_subtool.py:156: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
../../conda/envs/fre_cli/lib/python3.9/shutil.py:734: in rmtree
    _rmtree_safe_fd(fd, path, onerror)
../../conda/envs/fre_cli/lib/python3.9/shutil.py:667: in _rmtree_safe_fd
    _rmtree_safe_fd(dirfd, fullname, onerror)
...
...
...
../../conda/envs/fre_cli/lib/python3.9/shutil.py:690: in _rmtree_safe_fd
    onerror(os.unlink, fullname, sys.exc_info())
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

topfd = 28, path = 'fre/tests/test_files/outdir/tmp/CMIP6/CMIP6/ISMIP6/PCMDI/PCMDI-test-1-0/piControl-withism/r3i1p1f1/Omon/sos/gn/v20241022'
onerror = <function rmtree.<locals>.onerror at 0x2b0f0accbe50>

    def _rmtree_safe_fd(topfd, path, onerror):
...
...
...
...
>                   os.unlink(entry.name, dir_fd=topfd)
E                   OSError: [Errno 16] Device or resource busy: '.nfs00000000a9f8735600000090'

../../conda/envs/fre_cli/lib/python3.9/shutil.py:688: OSError
================================================================================ short test summary info =================================================================================
FAILED fre/cmor/tests/test_cmor_run_subtool.py::test_setup_fre_cmor_run_subtool_case2 - OSError: [Errno 16] Device or resource busy: '.nfs00000000a9f8735600000090'
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! stopping after 1 failures !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
============================================================================== 1 failed, 5 passed in 2.65s ===============================================================================

[ilaflott]

leaving this unresolved for now. the directory re-creation for the automatic test pipeline is a nice-to-have, not essential. as if you remove the directory by hand after erroring, and restart at this failed test, the test succeeds as expected.

largely that re-tests the directory creation that already succeeded in the prev test, so its even a tad redundant.

[ilaflott]

another reason to leave it unresolved- i suspect this is cmor's fault...

[ilaflott]

this will close #204

[ilaflott]

come a long way havent we...

[ilaflott]

regarding meniton in NOAA-GFDL/CatalogBuilder#79

links in commit point to https://github.com/NOAA-GFDL/MDTF-diagnostics/tree/main/data/gfdl-cmor-tables

note submodule dep: https://github.com/NOAA-GFDL/MDTF-diagnostics/tree/main/data/cmip6-cmor-tables comes from https://github.com/PCMDI/cmip6-cmor-tables