NCAR · jukent · May 17, 2023 · May 31, 2023 · May 31, 2023 · May 31, 2023
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -39,7 +39,7 @@ jobs:
           channels: conda-forge
           environment-file: build_envs/environment.yml
 
-      - name: Install geocat-comp
+      - name: Install geocat-viz
         run: |
           python -m pip install . --no-deps
 

diff --git a/.github/workflows/upstream-examples-ci.yml b/.github/workflows/upstream-examples-ci.yml
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,6 +9,9 @@ build:
   os: "ubuntu-20.04"
   tools:
     python: "mambaforge-4.10"
+  jobs:
+    post_create_environment:
+      - python -m pip install --no-cache-dir .
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

diff --git a/build_envs/docs.yml b/build_envs/docs.yml
@@ -14,5 +14,6 @@ dependencies:
   - nbsphinx
   - sphinx-design
   - xarray<=2023.02.0 #pin per issue https://github.com/NCAR/geocat-comp/issues/381
+  - geocat-datafiles
   - pip:
       - -e ..
diff --git a/build_envs/environment.yml b/build_envs/environment.yml
@@ -13,6 +13,7 @@ dependencies:
   - xarray<=2023.02.0 #pin per issue https://github.com/NCAR/geocat-comp/issues/381
   - metpy
   - pint
+  - geocat-datafiles
   - pip:
     - pre-commit
     - scikit-learn
diff --git a/build_envs/upstream-dev-environment.yml b/build_envs/upstream-dev-environment.yml
@@ -32,3 +32,4 @@ dependencies:
   - wrf-python
   - xarray<=2023.02.0 # pinned as per issue #98
   - pre-commit
+  - geocat-datafiles # for examples/tests
diff --git a/docs/_static/images/icons/electric_bolt.svg b/docs/_static/images/icons/electric_bolt.svg
diff --git a/docs/_static/images/icons/handshake.svg b/docs/_static/images/icons/handshake.svg
diff --git a/docs/_static/images/icons/menu_book.svg b/docs/_static/images/icons/menu_book.svg
diff --git a/docs/_static/images/icons/science.svg b/docs/_static/images/icons/science.svg
diff --git a/docs/_static/images/icons/tips.svg b/docs/_static/images/icons/tips.svg
diff --git a/docs/_static/thumbnails/add_height_from_pressure_axis.png b/docs/_static/thumbnails/add_height_from_pressure_axis.png
diff --git a/docs/_static/thumbnails/add_lat_lon_gridlines.png b/docs/_static/thumbnails/add_lat_lon_gridlines.png
diff --git a/docs/_static/thumbnails/add_lat_lon_ticklabels.png b/docs/_static/thumbnails/add_lat_lon_ticklabels.png
diff --git a/docs/_static/thumbnails/add_major_minor_ticks.png b/docs/_static/thumbnails/add_major_minor_ticks.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -319,6 +319,43 @@ def __getattr__(cls, name):
 
 autodoc_typehints = 'none'
 
+
+# custom scripts for making a gallery of examples notebooks
+# note: this method only supports a single gallery
+def update_gallery(app: Sphinx):
+    """Update the gallery of examples notebooks."""
+
+    LOGGER.info("creating gallery...")
+
+    notebooks = yaml.safe_load(
+        pathlib.Path(app.srcdir, "gallery.yml").read_bytes())
+
+    items = [
+        f"""
+         .. grid-item-card::
+            :text-align: center
+            :link: {item['path']}
+
+            .. image:: {item['thumbnail']}
+                :alt: {item['title']}
+            +++
+            {item['title']}
+            """ for item in notebooks
+    ]
+
+    items_md = indent(dedent("\n".join(items)), prefix="    ")
+    markdown = f"""
+.. grid:: 1 2 3 3
+    :gutter: 2
+
+    {items_md}
+    """
+
+    pathlib.Path(app.srcdir, "notebook-examples.txt").write_text(markdown)
+
+    LOGGER.info("gallery created")
+
+
 # turn off notebook execution
 # set to "auto" for default behavior
 nb_execution_mode = "off"
@@ -330,3 +367,4 @@ def __getattr__(cls, name):
 # Allow for changes to be made to the css in the theme_overrides file
 def setup(app):
     app.add_css_file('theme_overrides.css')
+    app.connect("builder-inited", update_gallery)
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -5,7 +5,20 @@
 Usage Examples
 ==============
 
-Examples showing GeoCAT-viz functions  and classes being utilized in real-world use
+More complex examples showing GeoCAT-viz functions  and classes being utilized in real-world use
 cases can be found at `GeoCAT-Examples gallery
 <https://geocat-examples.readthedocs.io/en/latest/gallery/index.html>`_.
-Additionally, each utility function has linked usage examples on their documentation pages.
+Each utility function has linked usage examples on their documentation pages.
+
+Here are some examples of how to use geocat-viz.
+
+.. include:: notebook-examples.txt
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   examples/util/add_height_from_pressure_axis.ipynb
+   examples/util/add_lat_lon_gridlines.ipynb
+   examples/util/add_lat_lon_ticklabels.ipynb
+   examples/util/add_major_minor_ticks.ipynb
diff --git a/docs/examples/taylor/add_bias_legend.py b/docs/examples/taylor/add_bias_legend.py
diff --git a/docs/examples/taylor/add_contours.py b/docs/examples/taylor/add_contours.py
diff --git a/docs/examples/taylor/add_grid.py b/docs/examples/taylor/add_grid.py
diff --git a/docs/examples/taylor/add_legend.py b/docs/examples/taylor/add_legend.py
diff --git a/docs/examples/taylor/add_model_name.py b/docs/examples/taylor/add_model_name.py
diff --git a/docs/examples/taylor/add_model_set.py b/docs/examples/taylor/add_model_set.py
diff --git a/docs/examples/taylor/add_title.py b/docs/examples/taylor/add_title.py
diff --git a/docs/examples/taylor/add_xgrid.py b/docs/examples/taylor/add_xgrid.py
diff --git a/docs/examples/taylor/add_ygrid.py b/docs/examples/taylor/add_ygrid.py
diff --git a/docs/examples/taylor/set_fontsizes_and_pad.py b/docs/examples/taylor/set_fontsizes_and_pad.py
diff --git a/docs/examples/util/add_height_from_pressure_axis.ipynb b/docs/examples/util/add_height_from_pressure_axis.ipynb
diff --git a/docs/examples/util/add_lat_lon_gridlines.ipynb b/docs/examples/util/add_lat_lon_gridlines.ipynb
diff --git a/docs/examples/util/add_lat_lon_ticklabels.ipynb b/docs/examples/util/add_lat_lon_ticklabels.ipynb
diff --git a/docs/examples/util/add_major_minor_ticks.ipynb b/docs/examples/util/add_major_minor_ticks.ipynb
diff --git a/docs/examples/util/add_right_hand_axis.py b/docs/examples/util/add_right_hand_axis.py
diff --git a/docs/examples/util/find_local_extrema.py b/docs/examples/util/find_local_extrema.py
diff --git a/docs/examples/util/get_skewt_vars.py b/docs/examples/util/get_skewt_vars.py
diff --git a/docs/examples/util/plot_contour_labels.py b/docs/examples/util/plot_contour_labels.py
diff --git a/docs/examples/util/plot_extrema_labels.py b/docs/examples/util/plot_extrema_labels.py
diff --git a/docs/examples/util/set_axes_limits_and_ticks.py b/docs/examples/util/set_axes_limits_and_ticks.py
diff --git a/docs/examples/util/set_map_boundary.py b/docs/examples/util/set_map_boundary.py
diff --git a/docs/examples/util/set_tick_direction_spine_visibility.py b/docs/examples/util/set_tick_direction_spine_visibility.py
diff --git a/docs/examples/util/set_titles_and_labels.py b/docs/examples/util/set_titles_and_labels.py
diff --git a/docs/examples/util/set_vector_density.py b/docs/examples/util/set_vector_density.py
diff --git a/docs/examples/util/truncate_colormap.py b/docs/examples/util/truncate_colormap.py
diff --git a/docs/examples/util/xr_add_cyclic_longitudes.py b/docs/examples/util/xr_add_cyclic_longitudes.py
diff --git a/docs/gallery.yml b/docs/gallery.yml
@@ -0,0 +1,15 @@
+- title: 'add_height_from_pressure_axis'
+  path: examples/util/add_height_from_pressure_axis.ipynb
+  thumbnail: _static/thumbnails/add_height_from_pressure_axis.png
+
+- title: 'add_lat_lon_gridlines'
+  path: examples/util/add_lat_lon_gridlines.ipynb
+  thumbnail: _static/thumbnails/add_lat_lon_gridlines.png
+
+- title: 'add_lat_lon_ticklabels'
+  path: examples/util/add_lat_lon_ticklabels.ipynb
+  thumbnail: _static/thumbnails/add_lat_lon_ticklabels.png
+
+- title: 'add_major_minor_ticks'
+  path: examples/util/add_major_minor_ticks.ipynb
+  thumbnail: _static/thumbnails/add_major_minor_ticks.png
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -0,0 +1,36 @@
+.. currentmodule:: geocat.viz
+
+.. _getting-started:
+
+Getting Started
+===============
+This is a quick guide to getting set up and familiar with GeoCAT-viz. You'll get an overview of what geocat-viz is,
+why we made it, and what functionalities it provides. You'll also get quick installation instructions and some simple
+examples to get you started.
+
+.. grid:: 1 1 2 2
+    :gutter: 2
+
+    .. grid-item-card:: Overview
+        :class-title: custom-title
+        :class-body: custom-body
+        :img-top: _static/images/icons/handshake.svg
+        :link: getting_started/overview.rst
+
+        Get aquainted with GeoCAT-viz
+
+    .. grid-item-card::  Quick Installation
+        :class-title: custom-title
+        :class-body: custom-body
+        :img-top: _static/images/icons/electric_bolt.svg
+        :link: getting_started/quick-install.rst
+
+        The most basic installation instructions for GeoCAT-viz
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Getting Started
+
+   Overview <getting_started/overview.rst>
+   Quick Installation <getting_started/quick-install.rst>
diff --git a/docs/getting_started/overview.rst b/docs/getting_started/overview.rst
@@ -0,0 +1,40 @@
+.. currentmodule:: geocat.viz
+
+.. _overview:
+
+Overview
+========
+GeoCAT-viz is the visualization component of the `GeoCAT project <https://geocat.ucar.edu/>`__. It contains tools to help plot data,
+including convenience and plotting functions that are used to facilitate plotting geosciences data with Matplotlib, Cartopy,
+and possibly other Python ecosystem plotting packages. GeoCAT-viz allows Python users to more easily make figures
+that resemeble NCL's plotting outputs, as demonstrated in the
+`GeoCAT Examples gallery <https://geocat-examples.readthedocs.io/en/latest/gallery/index.html>`__,
+but also offers visualization functionality that may go beyond what NCL offers.
+It is a principle component of NCAR's `Pivot to Python Initiative <https://www.ncl.ucar.edu/Document/Pivot_to_Python/>`__.
+
+Why GeoCAT-viz?
+----------------
+GeoCAT-viz is a geoscience visualization Python package created as part of NCAR's `Pivot to Python Initiative <https://www.ncl.ucar.edu/Document/Pivot_to_Python/>`__.
+`NCL <https://www.ncl.ucar.edu/>`__, the prior language of choice for geoscience work, has been put into maintenance mode
+in favor of Python. This is due to Python's easy-to-learn, open-source nature and the benefits that provides. There are
+a plethora of scientific analysis packages designed for general use or for niche applications. Numerous tutorials exist
+for learning Python basics and for data analysis workflows. Python also enables scalability through parallel computation
+which was never possible with NCL, enabling geoscientists to tackle analysis workflows on large volumes of data.
+
+GeoCAT-viz draws from well-established analysis packages like `Matplotlib <https://matplotlib.org/>`__, `Cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__,
+and `MetPy <https://unidata.github.io/MetPy/>`__ to recreate and expand upon NCL
+visualization functionalities in pure Python.
+
+One of the main concerns we heard from scientists "pivoting" from NCL to Python is that they found it harder to make
+publication-ready figures in Python. The GeoCAT team was tasked with recreating the `NCL Visualization Gallery <https://www.ncl.ucar.edu/gallery.shtml>`__
+in Python so that former NCL users could find 1-to-1 plotting examples from a resource they could easily navigate and pinpoint.
+Our growing version of this gallery lives in the `GeoCAT Examples gallery <https://geocat-examples.readthedocs.io/en/latest/gallery/index.html>`__,
+which is a separate product that the GeoCAT-viz package. However, during its creation we identified several convenience functions
+that make it easier to, for example. set plotting settings such as fontsize to match the NCL style, or to create geoscience specific plots, such as skewT diagrams.
+Those functions live here in GeoCAT-viz and can be used to improve or augment your Python plotting routines.
+
+GeoCAT-viz's open-source nature allows for more community engagement than a traditional software development workflow
+does. As advances are made in the realm of geoscience, new tools will be needed to analyze new datasets. We are dedicated
+to addressing user needs and encourage users to submit feature requests and contributions to our GitHub as well as
+participate in discussions. See our :ref:`support` page for info on how to submit bug reports, request new
+features, and get involved.
diff --git a/docs/getting_started/quick-install.rst b/docs/getting_started/quick-install.rst
@@ -0,0 +1,25 @@
+.. currentmodule:: geocat.viz
+
+.. _quick_install:
+
+Quick Installation
+==================
+
+For complete instructions on the various ways to install geocat-viz (e.g.
+via pip or source), head to the complete `installation <../installation.rst>`__ page.
+
+Installing GeoCAT-viz in a Pre-existing Conda Environment
+----------------------------------------------------------
+
+1.  Make sure your conda is up to date by running this command from the
+    terminal::
+
+        conda update conda
+
+2.  Activate the conda environment where you intent to install ``geocat-viz``. In this example, the environment is called ``geocat``::
+
+        conda activate geocat
+
+3. Install geocat-viz::
+
+        conda install -c conda-forge geocat-viz
diff --git a/docs/index.rst b/docs/index.rst
@@ -35,6 +35,24 @@ plotting packages.
 .. grid:: 1 1 2 2
     :gutter: 2
 
+    .. grid-item-card:: Getting Started
+        :class-title: custom-title
+        :class-body: custom-body
+        :img-top: _static/images/icons/tips.svg
+        :link: getting-started
+        :link-type: doc
+
+        A good place to start for new users
+
+    .. grid-item-card::  Examples
+        :class-title: custom-title
+        :class-body: custom-body
+        :img-top: _static/images/icons/science.svg
+        :link: examples
+        :link-type: doc
+
+        A gallery of examples using GeoCAT-viz
+
     .. grid-item-card::  Installation
         :class-title: custom-title
         :class-body: custom-body