add coordinate criteria table in docs (#147)

* add coordinate criteria table in docs

* add criteria in index

* add regex table and what's new

* fix make docstring

Author: malmans2

.gitignore

@@ -69,7 +69,9 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
+doc/generated/
+cf_xarray/tests/_build/
 
 # PyBuilder
 target/

cf_xarray/scripts/make_doc.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+
+import os
+
+from pandas import DataFrame
+
+from cf_xarray.accessor import _AXIS_NAMES, _COORD_NAMES, coordinate_criteria, regex
+
+
+def main():
+    """
+    Make all additional files needed to build the documentations.
+    """
+
+    make_criteria_csv()
+    make_regex_csv()
+
+
+def make_criteria_csv():
+    """
+    Make criteria tables:
+        _build/csv/{all,axes,coords}_criteria.csv
+    """
+
+    csv_dir = "_build/csv"
+    os.makedirs(csv_dir, exist_ok=True)
+
+    # Criteria tables
+    df = DataFrame.from_dict(coordinate_criteria)
+    df = df.dropna(1, how="all")
+    df = df.applymap(lambda x: ", ".join(sorted(x)) if isinstance(x, tuple) else x)
+    df = df.sort_index(0).sort_index(1)
+
+    # All criteria
+    df.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.loc[sorted(keys)].dropna(1, how="all")
+        subdf = subdf.dropna(1, how="all").transpose()
+        subdf.to_csv(os.path.join(csv_dir, f"{name}_criteria.csv"))
+
+
+def make_regex_csv():
+    """
+    Make regex tables:
+        _build/csv/all_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.sort_index(1).transpose()
+    df.to_csv(os.path.join(csv_dir, "all_regex.csv"), header=False)
+
+
+if __name__ == "__main__":
+    main()

cf_xarray/tests/test_scripts.py

@@ -0,0 +1,32 @@
+import os
+
+from cf_xarray.scripts import make_doc
+
+
+def remove_if_exists(paths):
+    paths = [paths] if isinstance(paths, str) else paths
+    for path in paths:
+        if os.path.exists(path):
+            os.remove(path)
+
+
+def test_make_doc():
+
+    # Create/remove files from tests/,
+    # always return to original working directory
+    owd = os.getcwd()
+    os.chdir(os.path.dirname(__file__))
+    try:
+        names = [
+            "axes_criteria",
+            "coords_criteria",
+            "all_criteria",
+            "all_regex",
+        ]
+        tables_to_check = [f"_build/csv/{name}.csv" for name in names]
+        remove_if_exists(tables_to_check)
+
+        make_doc.main()
+        assert all(os.path.exists(path) for path in tables_to_check)
+    finally:
+        os.chdir(owd)

doc/conf.py

@@ -18,6 +18,9 @@
 import sphinx_autosummary_accessors
 
 import cf_xarray  # noqa
+from cf_xarray.scripts import make_doc
+
+make_doc.main()
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

doc/contributing.rst

@@ -32,6 +32,11 @@ This dictionary contains criteria for identifying axis and coords using CF attri
 
    ~accessor.coordinate_criteria
 
+.. csv-table::
+   :file: _build/csv/all_criteria.csv
+   :header-rows: 1
+   :stub-columns: 1
+
 Classes
 ~~~~~~~
 

doc/criteria.rst

@@ -0,0 +1,34 @@
+.. currentmodule:: xarray
+
+CF Criteria
+-----------
+
+Attributes
+~~~~~~~~~~
+Criteria for identifying variables using CF attributes.
+
+Axes
+====
+
+.. csv-table::
+   :file: _build/csv/axes_criteria.csv
+   :header-rows: 1
+   :stub-columns: 1
+
+Coordinates
+===========
+
+.. csv-table::
+   :file: _build/csv/coords_criteria.csv
+   :header-rows: 1
+   :stub-columns: 1
+
+
+Names
+~~~~~
+Regex used by :meth:`DataArray.cf.guess_coord_axis` and :meth:`Dataset.cf.guess_coord_axis` for identifying variables using their names.
+
+.. csv-table::
+   :file: _build/csv/all_regex.csv
+   :stub-columns: 1
+

doc/examples/introduction.ipynb

@@ -184,7 +184,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## What attributes have been discovered?\n"
+    "## What attributes have been discovered?\n",
+    "\n",
+    "The criteria for identifying variables using CF attributes are listed\n",
+    "[here](../criteria.rst).\n"
    ]
   },
   {
@@ -1028,7 +1031,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.8"
+   "version": "3.7.3"
   },
   "toc": {
    "base_numbering": 1,

doc/index.rst

@@ -39,6 +39,7 @@ Table of contents
    :maxdepth: 2
 
    examples/introduction
+   criteria
    whats-new
    roadmap
    contributing

doc/whats-new.rst

@@ -6,6 +6,7 @@ What's New
 v0.4.1 (unreleased)
 ===================
 
+- Added scripts to document CF criteria with tables. By `Mattia Almansi`_.
 - Support for ``.drop()``, ``.drop_vars()``, ``.drop_sel()``, ``.drop_dims()``, ``.set_coords()``, ``.reset_coords()``. By `Mattia Almansi`_.
 - Support for using ``standard_name`` in more functions. (:pr:`128`) By `Deepak Cherian`_
 - Allow ``DataArray.cf[]`` with standard names. By `Deepak Cherian`_

setup.cfg

@@ -116,6 +116,6 @@ test = pytest
 nobeep = True
 
 [rstcheck]
-ignore_roles=pr,issue
-ignore_directives=ipython,autodata
+ignore_roles=pr,issue,meth
+ignore_directives=ipython,autodata,csv-table
 ignore_messages=(is not referenced\.$)