Merge docs/dev into the GCPy 1.4.0 development stream

This merge brings the latest documentation updates for version 1.4.0
into the dev branch.  This is necessary so that we can test the
gcpy.file_regrid.py with the latest Python environment.

Further updates may be necessary in order to correct errors in
documentation.  We need to make sure that all examples are correct
before release.

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

CHANGELOG.md

@@ -43,6 +43,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Now use `pypdf` instead of `PyPDF2` in `plot.py` and `util.py`
 - Added coding suggestions made by `pylint` where possible
 - Abstracted and never-nested code from `six_plot` into functions (in `plot.py`)
+- Added `main()` routine to `gcpy/file_regrid.py`; Also added updates suggested by Pylint
+
+### Removed
+- Removed `gchp_is_pre_13_1` arguments & code from benchmarking routines
+- Removed `is_pre_13_1` tags from `*_benchmark.yml` config files
 
 ### Fixed
 - Generalized test for GCHP or GCClassic restart file in `regrid_restart_file.py`

README.md

@@ -13,38 +13,55 @@
 
 **GCPy** is a Python-based toolkit containing useful functions for working specifically with the GEOS-Chem model of atmospheric chemistry and composition.
 
-GCPy aims to build on the well-established scientific Python technical stack, leveraging tools like cartopy and xarray to simplify the task of working with model output and performing atmospheric chemistry analyses.
+**GCPy** aims to build on the well-established scientific Python technical stack, leveraging tools like **cartopy**, **numpy**, and **xarray** to simplify the task of working with GEOS-Chem model output and performing atmospheric chemistry analyses.
 
 
 ## What GCPy was intended to do:
 
-1. Produce plots and tables from GEOS-Chem output using simple function calls.
-2. Generate the standard evaluation plots and tables from GEOS-Chem benchmark output.
-3. Obtain GEOS-Chem's horizontal/vertical grid information.
-4. Implement GCHP-specific regridding functionalities (e.g. cubed-sphere to lat-lon regridding)
-5. Provide example scripts for creating specific types of plots or analysis from GEOS-Chem output.
+1. Produce plots and tables from [GEOS-Chem](https://geos-chem.readthedocs.io) output using simple function calls.
+2. Generate the standard evaluation plots and tables for GEOS-Chem benchmark simulations.
+3. Obtain GEOS-Chem's horizontal and vertical grid information.
+4. Implement [GCHP](https://gchp.readthedocs.io)-specific regridding functionalities (e.g. cubed-sphere to lat-lon regridding)
+5. Provide example scripts for creating specific types of plots or  analysis from GEOS-Chem output.
+6. Provide user-submitted scripts for specific applications related to GEOS-Chem and [HEMCO](https://hemco.readthedocs.io).
 
-## What GCPY was not intended to do:
+## What GCPy was not intended to do:
 
 1. General NetCDF file modification: (crop a domain, extract some variables):
-    * Use [xarray](http://xarray.pydata.org) instead.
-    * Also see [our *Working with netCDF data files* wiki page](http://wiki.geos-chem.org/Working_with_netCDF_data_files).
+    * Instead, use netCDF tools such as:
+	  * [xarray](http://xarray.pydata.org)
+	  * [netCDF operators (NCO)](https://nco.sourceforge.net)
+	  * [Climate Data Operators](https://mpimet.mpg.de/cdo) instead.
+    * Also see our [*Work with netCDF files* guide](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html) at [geos-chem.readthedocs.io](https://geos-chem.readthedocs.io)
+
 2. Statistical analysis:
-    * Use [scipy](http://www.scipy.org)/[scikit-learn](https://scikit-learn.org) tools instead
-3. Machine Learning:
-    * Use the standard machine learning utilities ([pytorch](https://pytorch.org), [tensorflow](https://www.tensorflow.org), [julia](https://julialang.org), etc.)
+    * Instead, use statistical tools such as:
+	  * Use [scipy](http://www.scipy.org)
+	  * [scikit-learn](https://scikit-learn.org)
+	  * [R](https://r-project.org)
+	  * etc
 
+3. Machine Learning:
+    * Instead, use machine learning tools such as:
+	  * [pytorch](https://pytorch.org),
+	  * [tensorflow](https://www.tensorflow.org)
+	  * [julia](https://julialang.org)
+	  * etc.
 
 ## Documentation:
 
 For more information on installing and using GCPy, visit the official documentation at [gcpy.readthedocs.io](https://gcpy.readthedocs.io/).
 
-
 ## License
 
-GCPy is distributed under the MIT license.  Please read the license documents LICENSE.txt and AUTHORS.txt, which are located in the root folder.
+GCPy is distributed under the MIT license.  Please see the [GCPy license agreement](https://github.com/geoschem/gcpy/blob/dev/LICENSE.txt) and [List of GCPy developers](https://github.com/geoschem/gcpy/blob/dev/AUTHORS.txt) for more information.
+
+## Requesting support
 
+To report a bug or suggest a new feature, please see our [Support
+Guidelines](https://github.com/geoschem/gcpy/blob/dev/SUPPORT.md).
 
-## Contact
+## Submitting new features
 
-To contact us, please [open a new issue on the issue tracker connected to this repository](https://github.com/geoschem/gcpy/issues/new/choose). You can ask a question, report a bug, or request a new feature.
+If you are interested in submitting code to GCPy, please see our
+[Contributing Guidelines](https://github.com/geoschem/gcpy/blob/dev/CONTRIBUTING.md).

docs/source/About-GCPy.rst

@@ -1,54 +1,100 @@
+.. |br| raw:: html
+
+   <br/>
+
 .. _about:
 
 ##########
 About GCPy
 ##########
 
-**GCPy** is a Python-based toolkit containing useful functions for
-working specifically with the GEOS-Chem model of atmospheric chemistry
-and composition.
+:program:`GCPy` is a Python-based toolkit containing useful functions for
+working specifically with the :program:`GEOS-Chem` model of
+atmospheric chemistry and composition.
 
-GCPy aims to build on the well-established scientific Python technical
-stack, leveraging tools like cartopy and xarray to simplify the task of
-working with model output and performing atmospheric chemistry analyses.
+GCPy aims to build on the well-established scientific
+Python technical stack, leveraging tools like :program:`cartopy`,
+:program:`numpy`, and :program:`xarray` to simplify the task of
+working with GEOS-Chem model output and performing atmospheric
+chemistry analyses.
 
 .. _about-what-gcpy-does:
 
 ============================
 What GCPy was intended to do
 ============================
 
-#. Produce plots and tables from GEOS-Chem output using simple function
+#. Produce plots and tables from `GEOS-Chem
+   <https://geos-chem.readthedocs.io>`_ output using simple function
    calls.
 #. Generate the standard evaluation plots and tables from GEOS-Chem
-   benchmark output.
-#. Obtain GEOS-Chem's horizontal/vertical grid information.
-#. Implement GCHP-specific regridding functionalities (e.g. cubed-sphere
-   to lat-lon regridding).
+   benchmark simulations.
+#. Obtain GEOS-Chem's horizontal and vertical grid information.
+#. Implement `GCHP <https://gchp.readthedocs.io>`_-specific regridding
+   functionalities (e.g. cubed-sphere to lat-lon regridding).
 #. Provide example scripts for creating specific types of plots or
    analysis from GEOS-Chem output.
+#. Provide user-submitted scripts for specific applications related to
+   GEOS-Chem and `HEMCO <https://hemco.readthedocs.io>`_.
 
 .. _about-what-gcpy-doesnt-do:
 
 ================================
-What GCPY was not intended to do
+What GCPy was not intended to do
 ================================
 
 #. General NetCDF file modification: (crop a domain, extract some variables):
 
-   -  Use `xarray <http://xarray.pydata.org>`__ instead.
-   -  Also see `Work with netCDF data files
+   -  Instead, use netCDF tools such as:
+
+      - `xarray <http://xarray.pydata.org>`_
+      - `netCDF Operators (NCO) <https://nco.sourceforge.net/>`_
+      - `Climate Data Operators (CDO) <https://mpimet.mpg.de/cdo>`_
+
+   -  Also see our `Work with netCDF data
       <https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html>`_
-      at the GEOS-Chem ReadTheDocs site.
+      guide at `geos-chem.readthedocs.io
+      <https://geos-chem.readthedocs.io>`_.
 
 #. Statistical analysis:
 
-   -  Use `scipy <http://www.scipy.org>`__ and `scikit-learn
-      <https://scikit-learn.org>`__ tools instead.
+   -  Instead, use statistical tools such as:
+
+      - `scipy <http://www.scipy.org>`_
+      - `scikit-learn <https://scikit-learn.org>`_
+      - `R <https://r-project.org>`_
+      - etc.
 
 #. Machine Learning:
 
-   -  Use the standard machine learning utilities
-      (`pytorch <https://pytorch.org>`__,
-      `tensorflow <https://www.tensorflow.org>`__,
-      `julia <https://julialang.org>`__, etc.).
+   -  Instead, use machine learning tools such as:
+
+      - `pytorch <https://pytorch.org>`_
+      - `tensorflow <https://www.tensorflow.org>`_
+      - `julia <https://julialang.org>`_
+      - etc.
+
+=======
+License
+=======
+
+GCPy is distributed under the `MIT license
+<https://opensource.org/license/mit/>`_.  Please see the `GCPy license
+agreement  <https://github.com/geoschem/gcpy/blob/dev/LICENSE.txt>`_
+and `List of GCPy developers
+<https://github.com/geoschem/gcpy/blob/dev/AUTHORS.txt>`_ for more
+information.
+
+==================
+Requesting support
+==================
+
+To report a bug or suggest a new feature, please see our `Support
+Guidelines <https://github.com/geoschem/gcpy/blob/dev/SUPPORT.md>`_.
+
+=======================
+Submitting new features
+=======================
+
+If you are interested in submitting code to GCPy, please see our
+`Contributing Guidelines <https://github.com/geoschem/gcpy/blob/dev/CONTRIBUTING.md>`_.