Merge pull request #22 from andrewdnolan/doc_updates

Update API documentation and switch to `@properties` for some `Descriptor` attributes.

Author: andrewdnolan

dev-environment.txt

@@ -25,6 +25,6 @@ pre-commit
 # Documentation
 sphinx
 myst-nb
-myst-parser
 sphinx-book-theme
 sphinx-copybutton
+sphinx-remove-toctrees

docs/conf.py

@@ -43,6 +43,8 @@ def setup(app):
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx_remove_toctrees',
 ]
 
 source_suffix = {
@@ -61,7 +63,8 @@ def setup(app):
         'cartopy': ('https://scitools.org.uk/cartopy/docs/latest/', None),
         'matplotlib': ('https://matplotlib.org/stable', None),
         'numpy': ('https://numpy.org/doc/stable', None),
-        'xarray': ('https://xarray.pydata.org/en/stable', None)
+        'python': ('https://docs.python.org/3/', None),
+        'xarray': ('https://xarray.pydata.org/en/stable', None),
         }
 
 # -- MyST settings -----------------------------------------------------------
@@ -87,4 +90,25 @@ def setup(app):
     "show_navbar_depth": 3
 }
 
-html_static_path = ['_static']
+remove_from_toctrees = ["developers_guide/generated/*"]
+
+autodoc_typehints = "none"
+
+copybutton_prompt_text = ">>> "
+
+# Napoleon configurations
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+    "cartopy.crs.Projection": ":class:`cartopy.crs.CRS`",
+    # objects without namespace: xarray
+    "DataArray": "~xarray.DataArray",
+    "Dataset": "~xarray.Dataset",
+    # matplotlib terms
+    "matplotlib axes object": ":py:class:`matplotlib axes object <matplotlib.axes.Axes>`",
+    # objects without namespace: numpy
+    "ndarray": "~numpy.ndarray",
+    "path-like": ":term:`path-like <path-like object>`",
+    "string": ":class:`string <str>`",
+}

docs/developers_guide/api.md

@@ -1,16 +1,42 @@
 (dev-api)=
 
-# API Reference 
-
 ```{eval-rst}
 .. currentmodule:: mosaic
 
+.. _api: 
+
+API Reference 
+=============
+
+This page provides an auto-generated summary of mosaic's API.
+
+Top Level Utilities
+-------------------
 .. autosummary::
     :toctree: generated/
 
     polypcolor
     Descriptor
     datasets.open_dataset
-```
 
+Descriptor
+----------
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
 
+    Descriptor
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+
+    Descriptor.cell_patches
+    Descriptor.edge_patches
+    Descriptor.vertex_patches
+    Descriptor.transform
+
+```

mosaic/datasets.py

@@ -43,7 +43,7 @@
 # idea borrowed/copied from xarray
 def open_dataset(
     name: str,
-    cache_dir: None | str | os.PathLike = None,
+    cache_dir: str | os.PathLike | None = None,
     cache: bool = True,
     **kwargs,
 ) -> Dataset:
@@ -67,7 +67,8 @@ def open_dataset(
     cache : bool, optional
         If True, then cache data locally for use on subsequent calls
     kwargs : dict, optional
-        Passed to xarray.open_dataset
+        Additional arguments passed on to :py:func:`xarray.open_dataset`.
+
     """
 
     # invalid dataset name requested