Documentation Updates 📖 (#35)

* adding an inital notebook

* initial commit of restructure

* updating index

* moving the files under source for build

* moving index to top level

* update badges

* adding notebook content

* restructure

* adding contributing

* adding conf.py

* updating the organization

* updating index.md

* quick fix

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* update doc.yml

* updates to readme badges

* badges updates

* Update docs/index.md

Co-authored-by: Jacob Tomlinson <[email protected]>

* fix index

* update index to cover the comments

* Edits.

Co-authored-by:  Max Jones <[email protected]>

* more edits.

* update the dos locations

* fix the bad link in tutorials

* Small fix

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Deepak Cherian <[email protected]>
Co-authored-by: Jacob Tomlinson <[email protected]>
Co-authored-by: dcherian <[email protected]>
Co-authored-by: Max Jones <[email protected]>

Author: 5 people

.readthedocs.yml

@@ -6,15 +6,8 @@ build:
   tools:
     python: 'mambaforge-4.10'
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-
 # Optionally set the version of Python and requirements required to build your docs
 conda:
   environment: ci/doc.yml
 
-python:
-  install:
-    - method: pip
-      path: .
+formats: []

README.md

@@ -1,10 +1,11 @@
 # cupy-xarray
 
+> [!IMPORTANT]
 > ⚠️ This project is looking for maintainers and contributors. Come help out!
 
-[![GitHub Workflow CI Status](https://img.shields.io/github/workflow/status/xarray-contrib/cupy-xarray/CI?logo=github&style=flat)](https://github.com/xarray-contrib/cupy-xarray/actions)
+![GitHub Workflow CI Status](https://img.shields.io/github/actions/workflow/status/xarray-contrib/cupy-xarray/pypi-release.yaml?style=flat)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/xarray-contrib/cupy-xarray/main.svg)](https://results.pre-commit.ci/latest/github/xarray-contrib/cupy-xarray/main)
-[![Documentation Status](https://readthedocs.org/projects/cupy-xarray/badge/?version=latest)](https://cupy-xarray.readthedocs.io/en/latest/?badge=latest)
+[![Documentation Status](https://readthedocs.org/projects/cupy-xarray/badge/?version=latest)](https://cupy-xarray.readthedocs.io)
 
 [![PyPI](https://img.shields.io/pypi/v/cupy-xarray.svg?style=flat)](https://pypi.org/project/cupy-xarray/)
 [![Conda-forge](https://img.shields.io/conda/vn/conda-forge/cupy-xarray.svg?style=flat)](https://anaconda.org/conda-forge/cupy-xarray)

ci/doc.yml

@@ -5,9 +5,10 @@ dependencies:
   - pip
   - python=3.10
   - sphinx
+  - sphinx-design
   - sphinx-copybutton
-  - numpydoc
   - sphinx-autosummary-accessors
+  - numpydoc
   - ipython
   - ipykernel
   - ipywidgets

docs/conf.py

@@ -10,7 +10,7 @@
 import sphinx_autosummary_accessors
 
 project = "cupy-xarray"
-copyright = "2022, cupy-xarray developers"
+copyright = "2023, cupy-xarray developers"
 author = "cupy-xarray developers"
 release = "v0.1"
 
@@ -20,15 +20,18 @@
 extensions = [
     # "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
-    # "sphinx.ext.autosummary",
+    "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
     "numpydoc",
     # "sphinx_autosummary_accessors",
     "IPython.sphinxext.ipython_directive",
+    "sphinx.ext.napoleon",
     "myst_nb",
+    # "nbsphinx",
     "sphinx_copybutton",
+    "sphinx_design",
 ]
 
 
@@ -56,3 +59,68 @@
     "cupy": ("https://docs.cupy.dev/en/latest", None),
     "xarray": ("http://docs.xarray.dev/en/latest/", None),
 }
+
+autosummary_generate = True
+autodoc_typehints = "none"
+
+# Napoleon configurations
+napoleon_google_docstring = False
+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>`",
+    # special terms
+    # "same type as caller": "*same type as caller*",  # does not work, yet
+    # "same type as values": "*same type as values*",  # does not work, yet
+    # stdlib type aliases
+    "MutableMapping": "~collections.abc.MutableMapping",
+    "sys.stdout": ":obj:`sys.stdout`",
+    "timedelta": "~datetime.timedelta",
+    "string": ":class:`string <str>`",
+    # numpy terms
+    "array_like": ":term:`array_like`",
+    "array-like": ":term:`array-like <array_like>`",
+    "scalar": ":term:`scalar`",
+    "array": ":term:`array`",
+    "hashable": ":term:`hashable <name>`",
+    # matplotlib terms
+    "color-like": ":py:func:`color-like <matplotlib.colors.is_color_like>`",
+    "matplotlib colormap name": ":doc:`matplotlib colormap name <matplotlib:gallery/color/colormap_reference>`",
+    "matplotlib axes object": ":py:class:`matplotlib axes object <matplotlib.axes.Axes>`",
+    "colormap": ":py:class:`colormap <matplotlib.colors.Colormap>`",
+    # objects without namespace: xarray
+    "DataArray": "~xarray.DataArray",
+    "Dataset": "~xarray.Dataset",
+    "Variable": "~xarray.Variable",
+    "DatasetGroupBy": "~xarray.core.groupby.DatasetGroupBy",
+    "DataArrayGroupBy": "~xarray.core.groupby.DataArrayGroupBy",
+    # objects without namespace: numpy
+    "ndarray": "~numpy.ndarray",
+    "DaskArray": "~dask.array.Array",
+    "MaskedArray": "~numpy.ma.MaskedArray",
+    "dtype": "~numpy.dtype",
+    "ComplexWarning": "~numpy.ComplexWarning",
+    # objects without namespace: pandas
+    "Index": "~pandas.Index",
+    "MultiIndex": "~pandas.MultiIndex",
+    "CategoricalIndex": "~pandas.CategoricalIndex",
+    "TimedeltaIndex": "~pandas.TimedeltaIndex",
+    "DatetimeIndex": "~pandas.DatetimeIndex",
+    "Series": "~pandas.Series",
+    "DataFrame": "~pandas.DataFrame",
+    "Categorical": "~pandas.Categorical",
+    "Path": "~~pathlib.Path",
+    # objects with abbreviated namespace (from pandas)
+    "pd.Index": "~pandas.Index",
+    "pd.NaT": "~pandas.NaT",
+}

docs/index.md

@@ -1,10 +1,86 @@
-# Welcome to cupy-xarray's documentation!
+# CuPy-Xarray: Xarray on GPUs!
+
+![GitHub Workflow CI Status](https://img.shields.io/github/actions/workflow/status/xarray-contrib/cupy-xarray/pypi-release.yaml?style=flat-square)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/xarray-contrib/cupy-xarray/main.svg?style=flat-square)](https://results.pre-commit.ci/latest/github/xarray-contrib/cupy-xarray/main)
+[![Documentation Status](https://readthedocs.org/projects/cupy-xarray/badge/?version=latest&style=flat-square)](https://cupy-xarray.readthedocs.io)
+[![license](https://img.shields.io/github/license/xarray-contrib/cupy-xarray.svg?style=flat-square)](https://github.com/xarray-contrib/cupy-xarray)
+
+[![PyPI](https://img.shields.io/pypi/v/cupy-xarray.svg?style=flat-square)](https://pypi.org/project/cupy-xarray/)
+[![Conda-forge](https://img.shields.io/conda/vn/conda-forge/cupy-xarray.svg?style=flat-square)](https://anaconda.org/conda-forge/cupy-xarray)
+
+[![NASA-80NSSC22K0345](https://img.shields.io/badge/NASA-80NSSC22K0345-blue?style=flat-square)](https://science.nasa.gov/open-science-overview)
+
+## Overview
+
+CuPy-Xarray is a Python library that leverages [CuPy](https://cupy.dev/), a GPU array library, and [Xarray](https://docs.xarray.dev/en/stable/), a library for multi-dimensional labeled array computations, to enable fast and efficient data processing on GPUs. By combining the capabilities of CuPy and Xarray, CuPy-Xarray provides a convenient interface for performing accelerated computations and analysis on large multidimensional datasets.
+
+## Installation
+
+CuPy-Xarray can be installed using `pip` or `conda`:
+
+From Conda Forge:
+
+```bash
+
+conda install cupy-xarray -c conda-forge
+```
+
+From PyPI:
+
+```bash
+pip install cupy-xarray
+```
+
+The latest version from Github:
+
+```bash
+pip install git+https://github.com/xarray-contrib/cupy-xarray.git
+```
+
+## Acknowledgements
+
+Large parts of this documentations comes from [SciPy 2023 Xarray on GPUs tutorial](https://negin513.github.io/cupy-xarray-tutorials/README.html) and [this NCAR tutorial to GPUs](https://github.com/NCAR/GPU_workshop/tree/workshop/13_CuPyAndLegate).
 
 ## Contents
 
 ```{eval-rst}
+
+**User Guide**:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: User Guide
+
+   source/cupy-basics
+   source/introduction
+   source/basic-computations
+   source/high-level-api
+   source/apply-ufunc
+   source/real-example-1
+
+
+**Tutorials & Presentations**:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials & Presentations
+
+   source/tutorials-and-presentations
+
+**Contributing**:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contributing
+
+   source/contributing
+
+
+**API Reference**:
+
 .. toctree::
    :maxdepth: 1
+   :caption: API Reference
 
-   quickstart
+   api
 ```