Skip to content

Commit

Permalink
API documentation (#81)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
keewis authored Oct 25, 2024
1 parent c97ac23 commit 65c4189
Show file tree
Hide file tree
Showing 14 changed files with 428 additions and 18 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ instance/

# Sphinx documentation
docs/_build/
docs/generated/

# PyBuilder
.pybuilder/
Expand Down
1 change: 1 addition & 0 deletions ci/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,4 @@ dependencies:
- pip
- pip:
- h3ronpy
- -e ..
35 changes: 35 additions & 0 deletions docs/api-hidden.rst
Original file line number Diff line number Diff line change
@@ -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
92 changes: 92 additions & 0 deletions docs/api.rst
Original file line number Diff line number Diff line change
@@ -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
45 changes: 44 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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 = {
Expand All @@ -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 -------------------------------------------------

Expand All @@ -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),
}
4 changes: 4 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
# welcome to the documentation of `xdggs`

```{toctree}
api.rst
```
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
16 changes: 13 additions & 3 deletions xdggs/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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",
]
47 changes: 40 additions & 7 deletions xdggs/accessor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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(
Expand All @@ -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)
Expand All @@ -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(
Expand All @@ -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(
Expand Down
Loading

0 comments on commit 65c4189

Please sign in to comment.