Enable API reference docs to show accessor methods (#44)

* Install cupy-core and xarray

The cupy-core package from conda-forge does not bring in CUDA dependencies and thus can be installed on CPU-only CI services. Xref conda-forge/cupy-feedstock#229

* Re-enable building of API page in docs/conf.py

See usage instructions in https://sphinx-autosummary-accessors.readthedocs.io/en/stable/usage.html. Also need to `import cupy_xarray` to fix `exception: no module named xarray.DataArray.cupy` error following xarray-contrib/sphinx-autosummary-accessors#107.

* Undocument Dataset.cupy.get

Fixes `AttributeError: type object 'CupyDatasetAccessor' has no attribute 'get'`

* Pip install cupy_xarray on readthedocs

* Remove numpydoc and use napolean only

* Put editable install in ci/doc.yml so no need to pip install separately

Xref https://docs.readthedocs.io/en/stable/faq.html#i-need-to-install-a-package-in-a-environment-with-pinned-versions

* Add minimal docstrings to accessor methods and attributes

Adding some docstrings to the is_cupy, as_cupy and as_numpy  methods, so that the API docs page looks like center-aligned.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.gitignore

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

ci/doc.yml

@@ -2,17 +2,19 @@ name: cupy-xarray-doc
 channels:
   - conda-forge
 dependencies:
+  - cupy-core
   - pip
   - python=3.10
   - sphinx
   - sphinx-design
   - sphinx-copybutton
   - sphinx-autosummary-accessors
-  - numpydoc
   - ipython
   - ipykernel
   - ipywidgets
   - furo
   - myst-nb
-  # - cupy
-  # - xarray
+  - xarray
+  - pip:
+      # relative to this file. Needs to be editable to be accepted.
+      - --editable ..

cupy_xarray/accessors.py

@@ -23,7 +23,14 @@ def __init__(self, da):
 
     @property
     def is_cupy(self):
-        """bool: The underlying data is a cupy array."""
+        """
+        Check to see if the underlying array is a cupy array.
+
+        Returns
+        -------
+        is_cupy: bool
+            Whether the underlying data is a cupy array.
+        """
         if isinstance(self.da.data, dask_array_type):
             return isinstance(self.da.data._meta, cp.ndarray)
         return isinstance(self.da.data, cp.ndarray)
@@ -75,7 +82,6 @@ def as_numpy(self):
         -------
         da: DataArray
             DataArray with underlying data cast to numpy.
-
         """
         if self.is_cupy:
             if isinstance(self.da.data, dask_array_type):
@@ -113,13 +119,27 @@ def __init__(self, ds):
 
     @property
     def is_cupy(self):
+        """
+        Check to see if the underlying array is a cupy array.
+
+        Returns
+        -------
+        is_cupy: bool
+            Whether the underlying data is a cupy array.
+        """
         return all([da.cupy.is_cupy for da in self.ds.data_vars.values()])
 
     def as_cupy(self):
+        """
+        Convert the Dataset's underlying array type to cupy.
+        """
         data_vars = {var: da.as_cupy() for var, da in self.ds.data_vars.items()}
         return Dataset(data_vars=data_vars, coords=self.ds.coords, attrs=self.ds.attrs)
 
     def as_numpy(self):
+        """
+        Converts the Dataset's underlying array type from cupy to numpy.
+        """
         if self.is_cupy:
             data_vars = {var: da.cupy.as_numpy() for var, da in self.ds.data_vars.items()}
             return Dataset(

docs/api.rst

@@ -51,4 +51,3 @@ Methods
 
     Dataset.cupy.as_cupy
     Dataset.cupy.as_numpy
-    Dataset.cupy.get

docs/conf.py

@@ -6,9 +6,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-# import cupy_xarray
 import sphinx_autosummary_accessors
 
+import cupy_xarray  # noqa: F401
+
 project = "cupy-xarray"
 copyright = "2023, cupy-xarray developers"
 author = "cupy-xarray developers"
@@ -24,10 +25,9 @@
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
-    "numpydoc",
-    # "sphinx_autosummary_accessors",
-    "IPython.sphinxext.ipython_directive",
     "sphinx.ext.napoleon",
+    "sphinx_autosummary_accessors",
+    "IPython.sphinxext.ipython_directive",
     "myst_nb",
     # "nbsphinx",
     "sphinx_copybutton",
@@ -41,7 +41,7 @@
 }
 
 templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "api.rst"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/contributing.rst

@@ -138,13 +138,13 @@ Contributing documentation
 ==========================
 
 We greatly appreciate documentation improvements. The docs are built from the docstrings
-in the code and the docs in the ``doc`` directory.
+in the code and the docs in the ``docs`` directory.
 
 To build the documentation, you will need to requirements listed in ``ci/doc.yml``.
 You can create an environment for building the documentation using::
 
     conda env create --file ci/doc.yml
-    conda activate cupy-xarray-docs
+    conda activate cupy-xarray-doc
 
 You can then build the documentation using::