Better docs (#265)

Author: dcherian

cf_xarray/scripts/make_doc.py

@@ -33,13 +33,13 @@ def make_criteria_csv():
     df = df.sort_index(axis=0).sort_index(axis=1)
 
     # All criteria
-    df.to_csv(os.path.join(csv_dir, "all_criteria.csv"))
+    df.transpose().to_csv(os.path.join(csv_dir, "all_criteria.csv"))
 
     # Axes and coordinates
     for keys, name in zip([_AXIS_NAMES, _COORD_NAMES], ["axes", "coords"]):
         subdf = df[sorted(keys)].dropna(axis=1, how="all")
         subdf = subdf.dropna(axis=1, how="all").transpose()
-        subdf.to_csv(os.path.join(csv_dir, f"{name}_criteria.csv"))
+        subdf.transpose().to_csv(os.path.join(csv_dir, f"{name}_criteria.csv"))
 
 
 def make_regex_csv():
@@ -51,7 +51,7 @@ def make_regex_csv():
     csv_dir = "_build/csv"
     os.makedirs(csv_dir, exist_ok=True)
     df = DataFrame(regex, index=[0])
-    df = df.applymap(lambda x: f"``{x}``")
+    df = df.applymap(lambda x: f"``{str(x)[11:-1]}``")
     df = df.sort_index(axis=1).transpose()
     df.to_csv(os.path.join(csv_dir, "all_regex.csv"), header=False)
 

ci/doc.yml

@@ -17,6 +17,7 @@ dependencies:
   - ipywidgets
   - pandas
   - pooch
-  - pydata-sphinx-theme
   - pip:
       - git+https://github.com/xarray-contrib/cf-xarray
+      - myst_nb
+      - sphinx-book-theme

doc/bounds.md

@@ -0,0 +1,2 @@
+# Bounds Variables
+

doc/conf.py

@@ -47,10 +47,9 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
     "numpydoc",
-    "IPython.sphinxext.ipython_console_highlighting",
-    "IPython.sphinxext.ipython_directive",
-    "nbsphinx",
     "sphinx_autosummary_accessors",
+    "IPython.sphinxext.ipython_directive",
+    "myst_nb",
 ]
 
 extlinks = {
@@ -145,22 +144,32 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = "sphinx_book_theme"
-html_theme = "pydata_sphinx_theme"
+html_theme = "sphinx_book_theme"
+# html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {
-    "github_url": "https://github.com/xarray-contrib/cf-xarray",
-    "use_edit_page_button": True,
-    "navbar_end": "search-field.html",
-}
+html_theme_options = dict(
+    # analytics_id=''  this is configured in rtfd.io
+    # canonical_url="",
+    repository_url="https://github.com/xarray-contrib/cf-xarray",
+    repository_branch="main",
+    path_to_docs="doc",
+    use_edit_page_button=True,
+    use_repository_button=True,
+    use_issues_button=True,
+    home_page_in_toc=False,
+    extra_navbar="",
+    navbar_footer_text="",
+    navbar_end="search-field.html",
+)
+
 
 html_context = {
     "github_user": "xarray-contrib",
     "github_repo": "cf-xarray",
-    "github_version": "master",
+    "github_version": "main",
     "doc_path": "doc",
 }
 
@@ -232,48 +241,6 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = "cf_xarraydoc"
 
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-# 'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-# 'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-# 'preamble': '',
-# }
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-# latex_documents = [
-#   ('index', 'cf_xarray.tex', u'cf_xarray Documentation',
-#    u'Deepak Cherian', 'manual'),
-# ]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
-
 # -- Options for manual page output --------------------------------------------
 
 # One entry per manual page. List of tuples
@@ -283,30 +250,6 @@
 # If true, show URL addresses after external links.
 # man_show_urls = False
 
-
-# -- Options for Texinfo output ------------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-# texinfo_documents = [
-#  ('index', 'cf_xarray', u'cf_xarray Documentation',
-#   author, 'cf_xarray', 'One line description of project.',
-#   'Miscellaneous'),
-# ]
-
-# Documents to append as an appendix to all manuals.
-# texinfo_appendices = []
-
-# If false, no module index is generated.
-# texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-# texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-# texinfo_no_detailmenu = False
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "xarray": ("http://xarray.pydata.org/en/stable/", None),

doc/coord_axes.md

@@ -0,0 +1,92 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+```{eval-rst}
+.. currentmodule:: xarray
+```
+
+# Axes and Coordinates
+
+One powerful feature of ``cf_xarray`` is the ability to refer to named dimensions by standard `axis` or `coordinate` names in Dataset or DataArray methods.
+
+For example, one can call `ds.cf.mean("latitude")` instead of `ds.mean("lat")`
+```{code-cell}
+from cf_xarray.datasets import airds
+
+# identical to airds.mean("lat")
+airds.cf.mean("latitude")
+```
+
+```{tip}
+Most xarray methods are wrapped by cf-xarray. Simply access them as `DataArray.cf.method(dim="latitude")` for example  and try it! If something does not work, please raise an issue.
+```
+
+## Coordinate Names
+How does this work? `cf_xarray` has an internal table of criteria (mostly copied from MetPy) that lets it identify specific coordinate names `"latitude", "longitude", "vertical", "time"`. 
+
+
+```{tip}
+See {ref}`custom_criteria` to find out how to define your own custom criteria.
+```
+
+This table lists these internal criteria 
+```{eval-rst}
+.. csv-table::
+   :file: _build/csv/coords_criteria.csv
+   :header-rows: 1
+   :stub-columns: 1
+```
+Any DataArray that has `standard_name: "latitude"` or `_CoordinateAxisType: "Lat"` or `"units": "degrees_north"` in its `attrs` will be identified as the `"latitude"` variable by cf-xarray.  Similarly for other coordinate names.
+
+
+## Axis Names
+Similar criteria exist for the concept of "axes".
+
+```{eval-rst}
+.. csv-table::
+   :file: _build/csv/axes_criteria.csv
+   :header-rows: 1
+   :stub-columns: 1
+```
+
+## `.axes` and  `.coordinates` properties
+Alternatively use the special properties {py:attr}`DataArray.cf.axes` or {py:attr}`DataArray.cf.coordinates` to access the variable names. These properties return dictionaries that map "CF names" to a list of variable names. Note that a list is always returned even if only one variable name matches the name `"latitude"` (for example).
+```{code-cell}
+airds.cf.axes
+```
+
+```{code-cell}
+airds.cf.coordinates
+```
+
+## Axes or Coordinate?
+
+TODO describe latitude vs Y; longitude vs X; vertical vs Z
+
+## Checking presence of axis or coordinate
+
+Note that a given "CF name" is only present if there is at least one variable that can be identified with that name. The `airds` dataset has no `"vertical"` coordinate or `"Z"` axis, so those keys are not present. So to check whether a `"vertical"` coordinate or `"Z"` axis is present, one can
+```{code-cell}
+"Z" in airds.cf.axes
+```
+```{code-cell}
+"vertical" in airds.cf.coordinates
+```
+
+Or one can check the dataset as a whole:
+```{code-cell}
+"Z" in airds.cf
+```
+
+
+
+## Using the repr
+It is always useful to check the variables identified by cf-xarray using the `repr`
+```{code-cell}
+airds.cf
+```

doc/criteria.rst

@@ -0,0 +1,14 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst    
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+```{eval-rst}
+.. currentmodule:: xarray
+```
+
+(custom_criteria)=
+# Custom Criteria

doc/custom-criteria.md

@@ -0,0 +1,2 @@
+Frequently Asked Questions
+--------------------------

doc/faq.rst

@@ -0,0 +1,54 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+```{eval-rst}
+.. currentmodule:: xarray
+```
+
+(flags)=
+# Flag Variables
+
+`cf_xarray` has some support for [flag variables](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags).
+
+```{code-cell}
+import cf_xarray
+import xarray as xr
+
+da = xr.DataArray(
+    [1, 2, 1, 1, 2, 2, 3, 3, 3, 3],
+    dims=("time",),
+    attrs={
+        "flag_values": [1, 2, 3],
+        "flag_meanings": "atlantic_ocean pacific_ocean indian_ocean",
+        "standard_name": "region",
+    },
+  name="region",
+)
+da.cf
+```
+
+Now you can perform meaningful boolean comparisons that take advantage of the `flag_meanings` attribute:
+```{code-cell}
+# compare to da == 1
+da.cf == "atlantic_ocean"
+```
+
+Similarly with membership tests using {py:meth}`DataArray.cf.isin`
+```{code-cell}
+# compare to da.isin([2, 3])
+da.cf.isin(["indian_ocean", "pacific_ocean"])
+```
+
+You can also check whether a DataArray has the appropriate attributes to be recognized as a flag variable.
+```{code-cell}
+da.cf.is_flag_variable
+```
+
+```{tip}
+`cf_xarray` does not support [flag masks](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags) yet but a Pull Request to add this functionality is very welcome!
+```

doc/flags.md

@@ -0,0 +1,24 @@
+```{eval-rst}
+.. currentmodule:: xarray
+```
+
+# How to use cf_xarray
+
+There are four ways one can use cf_xarray.
+
+## Use CF standard names 
+
+Use "CF names" like `standard_name`, coordinates like `"latitude"`, axes like `"X"` instead of actual variable names. For e.g.
+
+## Extract actual variable names 
+
+Use `cf_xarray` to extract the appropriate variable name through the properties: 
+
+
+## Rename to a custom vocabulary
+
+Use {py:meth}`Dataset.rename`, or {py:meth}`Dataset.cf.rename_like` to rename variables to your preferences
+
+## Define custom criteria for a custom vocabulary
+
+Define custom criteria to avoid explicity renaming but still work with your datasets using a custom vocabulary.