API documentation (#81)

* configure the api documentation

* document grid info objects

* expose the dggs info classes

* generate entries for the grid info objects

* add `xarray`, `numpy` and `pandas` intersphinx entries

* install the project

* expose the plotting mechanism

* get the documentation to pass without warnings

* minimal docstring for `HealpixInfo.nside`

* minimal docstring for `HealpixInfo.nest`

* remove `Dataset.dggs.explore`, which errors currently

* docstrings for `cell_centers` and `cell_boundaries`

* document `*.dggs.grid_info`

* docstring for `from_dict`

* remove the trailing slash from the toctree dir

* document `tutorial.open_dataset`

* clarify the role of the grid names

* set some generic aliases

* improve the docstrings of `index` and `coord`

* make `cell_ids` an alias of `coord`

* restructure the api docs

* document the healpix grid info object

* document the h3 grid info class

* don't document the `valid_parameters` class attribute

* don't count `unique` as a valid indexing scheme

* document `xdggs.decode`

* link to the documentation in the package metadata

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
 
 # PyBuilder
 .pybuilder/

ci/docs.yml

@@ -27,3 +27,4 @@ dependencies:
   - pip
   - pip:
       - h3ronpy
+      - -e ..

docs/api-hidden.rst

@@ -0,0 +1,35 @@
+:orphan:
+
+.. currentmodule:: xdggs
+
+.. autosummary::
+   :toctree: generated
+
+   DGGSInfo.resolution
+
+   DGGSInfo.from_dict
+   DGGSInfo.to_dict
+   DGGSInfo.cell_boundaries
+   DGGSInfo.cell_ids2geographic
+   DGGSInfo.geographic2cell_ids
+
+   HealpixInfo.resolution
+   HealpixInfo.indexing_scheme
+   HealpixInfo.valid_parameters
+   HealpixInfo.nside
+   HealpixInfo.nest
+
+   HealpixInfo.from_dict
+   HealpixInfo.to_dict
+   HealpixInfo.cell_boundaries
+   HealpixInfo.cell_ids2geographic
+   HealpixInfo.geographic2cell_ids
+
+   H3Info.resolution
+   H3Info.valid_parameters
+
+   H3Info.from_dict
+   H3Info.to_dict
+   H3Info.cell_boundaries
+   H3Info.cell_ids2geographic
+   H3Info.geographic2cell_ids

docs/api.rst

@@ -0,0 +1,92 @@
+.. _api:
+
+#############
+API reference
+#############
+
+Top-level functions
+===================
+
+.. currentmodule:: xdggs
+
+.. autosummary::
+   :toctree: generated
+
+   decode
+
+Grid parameter objects
+======================
+
+.. autosummary::
+   :toctree: generated
+
+   DGGSInfo
+
+   HealpixInfo
+   H3Info
+
+.. currentmodule:: xarray
+
+Dataset
+=======
+
+Parameters
+----------
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/accessor_attribute.rst
+
+   Dataset.dggs.grid_info
+   Dataset.dggs.params
+
+
+Data inference
+--------------
+
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/accessor_method.rst
+
+   Dataset.dggs.cell_centers
+   Dataset.dggs.cell_boundaries
+
+DataArray
+=========
+
+Parameters
+----------
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/accessor_attribute.rst
+
+   DataArray.dggs.grid_info
+   DataArray.dggs.params
+
+
+Data inference
+--------------
+
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/accessor_method.rst
+
+   DataArray.dggs.cell_centers
+   DataArray.dggs.cell_boundaries
+
+Plotting
+--------
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/accessor_method.rst
+
+   DataArray.dggs.explore
+
+Tutorial
+========
+
+.. currentmodule:: xdggs
+
+.. autosummary::
+   :toctree: generated
+
+   tutorial.open_dataset

docs/conf.py

@@ -1,6 +1,10 @@
 # -- Project information -----------------------------------------------------
 import datetime as dt
 
+import sphinx_autosummary_accessors
+
+import xdggs  # noqa: F401
+
 project = "xdggs"
 author = f"{project} developers"
 initial_year = "2023"
@@ -18,9 +22,13 @@
 extensions = [
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
     "IPython.sphinxext.ipython_directive",
     "IPython.sphinxext.ipython_console_highlighting",
     "myst_parser",
+    "sphinx_autosummary_accessors",
 ]
 
 extlinks = {
@@ -29,13 +37,42 @@
 }
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "directory"]
 
+# -- autosummary / autodoc ---------------------------------------------------
+
+autosummary_generate = True
+autodoc_typehints = "none"
+
+# -- napoleon ----------------------------------------------------------------
+
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+    # general terms
+    "sequence": ":term:`sequence`",
+    "iterable": ":term:`iterable`",
+    "callable": ":py:func:`callable`",
+    "dict_like": ":term:`dict-like <mapping>`",
+    "dict-like": ":term:`dict-like <mapping>`",
+    "path-like": ":term:`path-like <path-like object>`",
+    "mapping": ":term:`mapping`",
+    "file-like": ":term:`file-like <file-like object>`",
+    "any": ":py:class:`any <object>`",
+    # numpy terms
+    "array_like": ":term:`array_like`",
+    "array-like": ":term:`array-like <array_like>`",
+    "scalar": ":term:`scalar`",
+    "array": ":term:`array`",
+    "hashable": ":term:`hashable <name>`",
+}
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -54,4 +91,10 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "xarray": ("https://docs.xarray.dev/en/latest/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
+    "lonboard": ("https://developmentseed.org/lonboard/latest", None),
+    "healpy": ("https://healpy.readthedocs.io/en/latest", None),
+    "shapely": ("https://shapely.readthedocs.io/en/stable", None),
 }

docs/index.md

@@ -1 +1,5 @@
 # welcome to the documentation of `xdggs`
+
+```{toctree}
+api.rst
+```

pyproject.toml

@@ -46,7 +46,7 @@ dependencies = [
 ]
 
 [project.urls]
-# Home = "https://xdggs.readthedocs.io"
+Documentation = "https://xdggs.readthedocs.io"
 Repository = "https://github.com/xarray-contrib/xdggs"
 
 [tool.ruff]

xdggs/__init__.py

@@ -2,8 +2,9 @@
 
 import xdggs.tutorial  # noqa: F401
 from xdggs.accessor import DGGSAccessor  # noqa: F401
-from xdggs.h3 import H3Index
-from xdggs.healpix import HealpixIndex
+from xdggs.grid import DGGSInfo
+from xdggs.h3 import H3Index, H3Info
+from xdggs.healpix import HealpixIndex, HealpixInfo
 from xdggs.index import DGGSIndex, decode
 
 try:
@@ -12,4 +13,13 @@
     # package is not installed
     __version__ = "9999"
 
-__all__ = ["__version__", "DGGSIndex", "H3Index", "HealpixIndex", "decode"]
+__all__ = [
+    "__version__",
+    "DGGSInfo",
+    "H3Info",
+    "HealpixInfo",
+    "DGGSIndex",
+    "H3Index",
+    "HealpixIndex",
+    "decode",
+]

xdggs/accessor.py

@@ -31,20 +31,25 @@ def __init__(self, obj: xr.Dataset | xr.DataArray):
 
     @property
     def index(self) -> DGGSIndex:
-        """Returns the DGGSIndex instance for this Dataset or DataArray.
+        """The DGGSIndex instance for this Dataset or DataArray.
 
-        Raise a ``ValueError`` if no such index is found.
+        Raises
+        ------
+        ValueError
+            if no DGGSIndex can be found
         """
         if self._index is None:
             raise ValueError("no DGGSIndex found on this Dataset or DataArray")
         return self._index
 
     @property
     def coord(self) -> xr.DataArray:
-        """Returns the indexed DGGS (cell ids) coordinate as a DataArray.
-
-        Raise a ``ValueError`` if no such coordinate is found on this Dataset or DataArray.
+        """The indexed DGGS (cell ids) coordinate as a DataArray.
 
+        Raises
+        ------
+        ValueError
+            if no such coordinate is found on the Dataset / DataArray
         """
         if not self._name:
             raise ValueError(
@@ -59,6 +64,12 @@ def params(self) -> dict:
 
     @property
     def grid_info(self) -> DGGSInfo:
+        """The grid info object containing the DGGS type and its parameters.
+
+        Returns
+        -------
+        xdggs.DGGSInfo
+        """
         return self.index.grid_info
 
     def sel_latlon(
@@ -78,7 +89,6 @@ def sel_latlon(
         subset
             A new :py:class:`xarray.Dataset` or :py:class:`xarray.DataArray`
             with all cells that contain the input latitude/longitude data points.
-
         """
         cell_indexers = {
             self._name: self.grid_info.geographic2cell_ids(latitude, longitude)
@@ -98,9 +108,25 @@ def assign_latlon_coords(self) -> xr.Dataset | xr.DataArray:
 
     @property
     def cell_ids(self):
-        return self._obj[self._name]
+        """The indexed DGGS (cell ids) coordinate as a DataArray.
+
+        Alias of ``coord``.
+
+        Raises
+        ------
+        ValueError
+            if no such coordinate is found on the Dataset / DataArray
+        """
+        return self.coord
 
     def cell_centers(self):
+        """derive geographic cell center coordinates
+
+        Returns
+        -------
+        coords : xarray.Dataset
+            Dataset containing the cell centers in geographic coordinates.
+        """
         lon_data, lat_data = self.index.cell_centers()
 
         return xr.Dataset(
@@ -111,6 +137,13 @@ def cell_centers(self):
         )
 
     def cell_boundaries(self):
+        """derive cell boundary polygons
+
+        Returns
+        -------
+        boundaries : xarray.DataArray
+            The cell boundaries as shapely objects.
+        """
         boundaries = self.index.cell_boundaries()
 
         return xr.DataArray(