Enhance documentation (#7)

Changed to APACHE license; enhanced documentation

doc/conf.py

@@ -302,7 +302,8 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
-    'dask': ('https://dask.pydata.org/en/latest/', None),
+    'dask': ('https://docs.dask.org/en/latest/', None),
+    'distributed': ('https://distributed.dask.org/en/latest/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'numba': ('https://numba.pydata.org/numba-doc/latest/', None),

doc/index.rst

@@ -1,5 +1,36 @@
 xarray_extras: Advanced algorithms for xarray
 =============================================
+This module offers several extensions to :mod:`xarray`, which could not be
+included into the main xarray module because they fall into one or more of the
+following categories:
+
+- They're too experimental
+- They're too niche
+- They introduce major new dependencies (e.g. :mod:`numba` or a C compiler)
+- They would be better done by doing major rework on multiple packages, and
+  then one would need to wait for said changes to reach a stable release of
+  each package - *in the right order*.
+
+The API of xarray-extras is unstable by definition, as features will be
+progressively migrated upwards towards xarray, dask, numpy etc.
+
+Features
+--------
+:doc:`api/csv`
+    Multi-threaded CSV writer, much faster than
+    :meth:`pandas.DataFrame.to_csv`, with full support for :mod:`dask` and
+    :mod:`distributed`
+:doc:`api/cumulatives`
+    Advanced cumulative sum/productory/mean functions
+:doc:`api/interpolate`
+    dask-optimized n-dimensional spline interpolation
+:doc:`api/numba_extras`
+    Additions to :mod:`numba`
+:doc:`api/sort`
+    Advanced sort/take functions
+
+Index
+-----
 
 .. toctree::
 
@@ -20,6 +51,6 @@ API Reference
 License
 -------
 
-xarray_extras is available under the open source `LGPL License`__.
+xarray-extras is available under the open source `Apache License`__.
 
-__ https://www.gnu.org/licenses/lgpl-3.0.en.html
+__ http://www.apache.org/licenses/LICENSE-2.0.html

doc/installing.rst

@@ -13,6 +13,13 @@ Required dependencies
 - `numba <http://numba.pydata.org>`__
 - C compiler (only if building from sources)
 
+Deployment
+----------
+
+- With pip: :command:`pip install xarray-extras`
+- With `anaconda <https://www.anaconda.com/>`_:
+  :command:`conda install -c conda-forge xarray-extras`
+
 Testing
 -------
 

doc/whats-new.rst

@@ -16,6 +16,7 @@ What's New
 
 v0.3.0 (unreleased)
 -------------------
+- Changed license to Apache 2.0
 
 
 .. _whats-new.0.2.2:

xarray_extras/csv.py

@@ -1,4 +1,6 @@
-"""CSV file type support
+"""Multi-threaded CSV writer, much faster than
+:meth:`pandas.DataFrame.to_csv`, with full support for :mod:`dask` and
+:mod:`distributed`
 """
 import xarray
 from dask.base import tokenize
@@ -13,7 +15,8 @@
 def to_csv(x, path, *, nogil=True, **kwargs):
     """Print DataArray to CSV.
 
-    When x has numpy backend, this function is equivalent to::
+    When x has numpy backend, this function is functionally equivalent to (but
+    much) faster than)::
 
         x.to_pandas().to_csv(path_or_buf, **kwargs)
 

xarray_extras/cumulatives.py

@@ -1,4 +1,4 @@
-"""xarray extensions to cumsum and cumprod
+"""Advanced cumulative sum/productory/mean functions
 """
 import dask.array as da
 import numpy as np

xarray_extras/interpolate.py

@@ -1,4 +1,4 @@
-"""xarray interpolation functions
+"""xarray spline interpolation functions
 """
 import xarray
 import numpy as np