Prepare release 0.1.0

.github/workflows/pypipublish.yaml

@@ -0,0 +1,26 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2.3.4
+      - name: Set up Python
+        uses: actions/setup-python@v2.1.4
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install setuptools setuptools-scm wheel twine
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          python setup.py sdist bdist_wheel
+          twine upload dist/*

README.md

@@ -5,4 +5,46 @@
 [![Documentation Status](https://readthedocs.org/projects/xoak/badge/?version=latest)](https://xoak.readthedocs.io/en/latest/?badge=latest)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ESM-VFC/xoak/master?filepath=doc%2Fexamples)
 
-Xoak is an Xarray extension that provides specific indexes for selecting irregular, n-dimensional data.
+Xoak is an Xarray extension that allows point-wise selection of irregular,
+n-dimensional data encoded in coordinates with an arbitrary number of
+dimensions.
+
+It provides a built-in index adapter for
+[Scipy](https://docs.scipy.org/doc/scipy/reference/)'s `cKDTree`, as well as
+adapters for index structures implemented in these 3rd-party libraries (optional
+dependencies):
+
+- [Scikit-Learn](https://scikit-learn.org): `BallTree` and `KDTree`, which
+  support various distance metrics.
+- [pys2index](https://github.com/benbovy/pys2index): `S2PointIndex` for
+  efficient indexing of lat/lon point data, based on `s2geometry`.
+
+Xoak also provides a mechanism for easily adding and registering custom index adapters.
+
+## Install
+
+Xoak can be installed using conda (or mamba):
+
+```bash
+$ conda install xoak -c conda-forge
+```
+
+or pip:
+
+```bash
+$ python -m pip install xoak
+```
+
+Xoak's optional dependencies can be installed using conda:
+
+```bash
+$ conda install scikit-learn pys2index -c conda-forge
+```
+
+## Documentation
+
+Documentation is hosted on ReadTheDocs: https://xoak.readthedocs.io/
+
+## License
+
+MIT License, see LICENSE file.

doc/examples/custom_indexes.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Custom Indexes\n",
     "\n",
-    "While `xoak` provides some built-in index adapters, it is easy to adapt and register new indexes. "
+    "While Xoak provides some built-in index adapters, it is easy to adapt and register new indexes. "
    ]
   },
   {
@@ -24,7 +24,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "An instance of `xoak.IndexRegistry` by default contains a collection of `xoak` built-in index adapters:"
+    "An instance of `xoak.IndexRegistry` by default contains a collection of Xoak built-in index adapters:"
    ]
   },
   {
@@ -44,7 +44,7 @@
    "source": [
     "## Example: add a brute-force \"index\"\n",
     "\n",
-    "Every `xoak` supported index is a subclass of `xoak.IndexAdapter` that must implement the `build` and `query` methods. The `IndexRegistry.register` decorator may be used to register a new index adpater.\n",
+    "Every Xoak supported index is a subclass of `xoak.IndexAdapter` that must implement the `build` and `query` methods. The `IndexRegistry.register` decorator may be used to register a new index adpater.\n",
     "\n",
     "Let's create and register a new adapter, which simply performs brute-force nearest-neighbor lookup by computing the pairwise distances between all index and query points and finding the minimum distance. "
    ]

doc/examples/dask_support.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "**Note: this feature is experimental!**\n",
     "\n",
-    "When the dataset have chunked coordinates (dask arrays), `xoak` may build the index and/or performs the selection in-parallel. "
+    "When the dataset have chunked coordinates (dask arrays), Xoak may build the index and/or performs the selection in-parallel. "
    ]
   },
   {
@@ -59,7 +59,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`xoak` builds an index structure for each chunk (all coordinates must have the same chunks):"
+    "Xoak builds an index structure for each chunk (all coordinates must have the same chunks):"
    ]
   },
   {

doc/examples/introduction.ipynb

@@ -4,9 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Introduction to `xoak`\n",
+    "# Introduction to Xoak\n",
     "\n",
-    "This notebook briefly shows how to use `xoak` with `xarray`'s [advanced indexing](http://xarray.pydata.org/en/stable/indexing.html#more-advanced-indexing) to perform point-wise selection of irrelgularly spaced data encoded in coordinates with an arbitrary number of dimensions (1, 2, ..., n-d)."
+    "This notebook briefly shows how to use Xoak with Xarray's [advanced indexing](http://xarray.pydata.org/en/stable/indexing.html#more-advanced-indexing) to perform point-wise selection of irrelgularly spaced data encoded in coordinates with an arbitrary number of dimensions (1, 2, ..., n-d)."
    ]
   },
   {
@@ -26,7 +26,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's first create an `xarray.Dataset` of latitude / longitude points located randomly on the sphere, forming a 2-dimensional (x, y) model mesh (note that `xoak` supports indexing coordinates with an arbitrary number of dimensions)."
+    "Let's first create an `xarray.Dataset` of latitude / longitude points located randomly on the sphere, forming a 2-dimensional (x, y) model mesh (note that Xoak supports indexing coordinates with an arbitrary number of dimensions)."
    ]
   },
   {
@@ -60,7 +60,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We first need to build an index to allow fast point-wise selection. `xoak` supports several indexes that can be used depending on the data. Here we use the `sklearn_geo_balltree` index, a wrapper around [sklearn.BallTree](https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.BallTree.html#sklearn.neighbors.BallTree) using the Haversine distance metric that is suited for indexing latitude / longitude points.\n",
+    "We first need to build an index to allow fast point-wise selection. Xoak supports several indexes that can be used depending on the data. Here we use the `sklearn_geo_balltree` index, a wrapper around [sklearn.BallTree](https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.BallTree.html#sklearn.neighbors.BallTree) using the Haversine distance metric that is suited for indexing latitude / longitude points.\n",
     "\n",
     "With this index, it is important to specify `lat` and `lon` in this specific order. Both the `lat` and `lon` coordinates must have exactly the same dimensions in the same order, here `('x', 'y')`."
    ]
@@ -139,7 +139,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`xoak` also supports providing coordinates with an arbitrary number of dimensions as indexers, like in the example below with vertices of another mesh on the sphere. "
+    "Xoak also supports providing coordinates with an arbitrary number of dimensions as indexers, like in the example below with vertices of another mesh on the sphere. "
    ]
   },
   {

doc/index.rst

@@ -7,9 +7,21 @@ irregular, n-dimensional data.
 Table of contents
 -----------------
 
-**Help & Reference**
+**Getting Started**
 
+* :doc:`install`
 * :doc:`examples/index`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Getting Started
+
+   install
+   examples/index
+
+**Help & Reference**
+
 * :doc:`api`
 * :doc:`release_notes`
 
@@ -18,7 +30,6 @@ Table of contents
    :hidden:
    :caption: Help & Reference
 
-   examples/index
    api
    release_notes
 

doc/install.rst

@@ -0,0 +1,63 @@
+.. _install:
+
+Install xoak
+============
+
+Required dependencies
+---------------------
+
+- Python 3.6 or later.
+- `xarray <http://xarray.pydata.org>`__
+- `dask <https://docs.dask.org>`__
+- `scipy <https://docs.scipy.org/doc/scipy/reference/>`__
+
+Optional dependencies
+---------------------
+
+Xoak provides built-in adapters for some indexes implemented in the 3rd-party
+libraries listed below. Those dependencies are optional: adapters won't be
+added in Xoak's index registry if they are not installed.
+
+- `scikit-learn <https://scikit-learn.org>`__
+- `pys2index <https://github.com/benbovy/pys2index>`__
+
+Install using conda
+-------------------
+
+Xoak can be installed or updated using conda_ (or mamba_)::
+
+  $ conda install xoak -c conda-forge
+
+This installs Xoak and all its required dependencies. The optional dependencies
+listed above could be installed separately using conda too::
+
+  $ conda install scikit-learn pys2index -c conda-forge
+
+The xoak conda package is maintained on the `conda-forge`_ channel.
+
+.. _conda-forge: https://conda-forge.org/
+.. _conda: https://conda.io/docs/
+.. _mamba: https://github.com/mamba-org/mamba
+
+Install using pip
+-----------------
+
+You can also install Xoak and its required dependencies using pip_::
+
+  $ python -m pip install xoak
+
+.. _pip: https://pip.pypa.io
+
+Install from source
+-------------------
+
+See Section :ref:`contribute` for instructions on how to setup a development
+environment for Xoak.
+
+Import xoak
+-----------
+
+To make sure that Xoak is correctly installed, try to import it by running this
+line::
+
+    $ python -c "import xoak"

doc/release_notes.rst

@@ -3,5 +3,7 @@
 Release Notes
 =============
 
-v0.1.0 (Unreleased)
--------------------
+v0.1.0 (17 December 2020)
+-------------------------
+
+Initial release.

environment.yml

@@ -14,7 +14,6 @@ dependencies:
   - notebook
   - ipykernel
   - matplotlib
-  - pys2index
   - pip
   - pip:
       - git+https://github.com/ESM-VFC/xoak

setup.py

@@ -38,9 +38,9 @@
     packages=find_packages(where='src'),
     package_dir={'': 'src'},
     include_package_data=True,
-    install_requires=['xarray', 'numpy', 'dask', 'scikit-learn'],
+    install_requires=['xarray', 'numpy', 'dask', 'scipy'],
     extras_require={
-        'dev': ['pytest', 'pytest-cov', 'pre-commit'],
+        'dev': ['scikit-learn', 'pytest', 'pytest-cov', 'pre-commit'],
     },
     license='MIT',
     zip_safe=False,