[Doc]: Routine review of documentation for accuracy and relevancy

[tomvothecoder]

Describe your documentation update

As suggested by @pochedls, we should perform a routine review of our documentation for accuracy and make sure all information is up-to-date and relevant.

[pochedls]

For Users

• Getting Started ( [PR]: Simplify the contributing guide #593, will be renamed to "Installation")
• xCDAT on Jupyter and HPC Machines (Update FAQs, HPC guide, and Gentle Introduction #650)
• Frequently Asked Questions (Update FAQs, HPC guide, and Gentle Introduction #650)

Gallery

• A Gentle Introduction to xCDAT (Xarray Climate Data Analysis Tools) (Update FAQs, HPC guide, and Gentle Introduction #650)
• General Dataset Utilities (Review of spatial averaging and general dataset utilities #644)
• Calculate Geospatial Weighted Averages from Monthly Time Series (Review of spatial averaging and general dataset utilities #644)
• Calculate Time Averages from Time Series Data (Temporal average notebooks maintanance #633)
• Calculating Climatology and Departures from Time Series Data (Temporal average notebooks maintanance #633)
• Horizontal Regridding (Update regridding notebook for v0.7.0 #646)
• Vertical Regridding (Update regridding notebook for v0.7.0 #646)

• I didn't list "Presentations & Demos," "API Reference," or "Changelog"

[pochedls]

Review of Spatial Averaging Notebook

• Give this a simpler title (perhaps with a more descriptive subtitle)
• Reduce header information
  • Put authors in-line (e.g., Authors: Tom Vo and Stephen Po-Chedley)
  • Update date and include version (Updated XX/YY/ZZZZ using xcdat v0.x.y)
  • Put the data note at the end of the overview instead of the header: The data used in this example is used directly from the [Earth System Grid Federation (ESGF)](https://aims2.llnl.gov/metagrid/search).
• Notebook Setup: I think this section could be combined with Overview (make it Overview and Setup) and we should systematically point the users to our setup pages instead of documenting this in each notebook:

Users can install their own instance of xcdat and follow these examples using their own environment (e.g., with vscode, Jupyter, Spyder, iPython) or enable xcdat with existing JupyterHub instances.

• Do we need this: %matplotlib inline? It seems like it doesn't do anything.
• We don't need to print out the dataset for each of the three domains
• Add example with keep_weights=True and then plot the weights
• Show an example of passing in your own weights (tropical, precipitation weighted SST)
  • Could also show the .spatial.get_weights() function here
  • This brings up another issue. We should note that lat_bounds and lon_bounds don't do anything in this case (and we should make sure this is noted in the docstrings).
• We should show an example of zonal averaging
• In the plots, we should add a better title (e.g., title=Nino 3.4 time series)
• In the Nino 3.4 description it seems like we have stray quote block mark down stuff (>)
• Could potentially include an example where bounds are missing and need to be added

[pochedls]

Spatial averaging is done (pending a PR). I will also review General Dataset Utilities.

[chengzhuzhang]

A minor glitch: in the linked notebook (https://github.com/pochedls/xcdat/blob/589-doc-reviews/docs/examples/spatial-average.ipynb). The ^{\ \circ} } didn't work to produce degree symbol? Maybe use ^{\circ} in math mode instead?

[pochedls]

@chengzhuzhang – these are only supposed to produce degree symbols in the plots – I think they are rendering correctly in the plots? Or am I looking at the wrong thing?

[chengzhuzhang]

Oh, it is a false alarm. I was trying to mimic your PR, but for regridding. The first lines of some output included the string in math mode which confused me, the figures are indeed fine.

[tomvothecoder]

This is now complete with all of the merged PRs.