prepare release

Author: strawpants

README.md

@@ -5,22 +5,37 @@
 
 This extension adds functionality to work with Spherical Harmonics to [Xarray](https://github.com/pydata/xarray).
 
-## Features and functionality (in progress)
+
+## Features and functionality 
 * Gravity functionals: (convert from Stokes coefficients to various gravity functionals, such as equivalent water heights, geoid changes, etc.)
 * Filter (e.g. Gaussian or anisotropic filter applied in the spectral domain)
-* The use of Xarray like operations allow for applying functionality to multi-dimensional datasets
-
+* The use of Xarray-like operations allow for applying functionality to multi-dimensional datasets
+* A spectral sea level equation solver
 
 ## Getting started
-The tutorials in the [documentation](https://shxarray.wobbly.earth/stable/tutorial.html) will gradually epxand and provide Jupyter notebook workflows to start with.
+The tutorials in the [documentation](https://shxarray.wobbly.earth/stable/tutorial.html) provide Jupyter Notebooks with examples of how to make use of the module. The notebooks can also be found on the [github repository](https://github.com/ITC-Water-Resources/shxarray/tree/main/docs/source/notebooks).
 
+The functionality of shxarray becomes available when importing the module together with Xarray:
+
+```
+import shxarray
+import xarray as xr
+```
+after which the shxarray accessor becomes available for use, e.g.:
+```
+nmax=20
+nmin=2
+dazeros=xr.DataArray.sh.ones(nmax=nmax,nmin=nmin)
+```
 
 ## Installation
 You can install this package from PyPi using:
 ```
 pip install shxarray
 ```
 
+## Backends
+Shxarray comes with a default **shlib** backend written in C++ and Cython. In addition, a very fast 'shtns' backend can be used when [SHTns](https://nschaeff.bitbucket.io/shtns/) is installed. The backends can be specified in enabled routines as the options: `engine='shlib'` or `engine='shtns'`.
 
 ## Development Installation
 If you want to help in the development of this package, it's best to clone the repository to allow for modifications and pull requests. The extension makes use of [Cython](https://cython.readthedocs.io/en/latest/) generated code to speed up spherical harmonic synthesis and analysis.
@@ -41,15 +56,15 @@ will be much faster than using
 ```pip install -e .``` 
 
 
-This will build the shared library in for example `./build/lib.linux-x86_64-cpython-3xx/shxarray/shlib.cpython-3xx-x86_64-linux-gnu.so`. To make sure changes are picked up in your editable install you can create a symbolic link in the Python part of the library e.g. :
+This will build the shared library in for example `./build/lib.linux-x86_64-cpython-3xx/shxarray/shlib.cpython-3xx-x86_64-linux-gnu.so`. To make sure changes are picked up in your editable install you should create a symbolic link in the Python part of the library e.g. :
 
 ```
 cd src/shxarray/
 ln -sf ../../build/lib.linux-x86_64-cpython-311/shxarray/shlib.cpython-311-x86_64-linux-gnu.so
 ```
 
 ### Numpy version issues
-The provided c++ files are cythonized against numpy > 2. When building against older numpy versions (<2), the cpp files are re-cythonized upon install, this requires a working cython install.
+The provided c++ files are cythonized against numpy > 2. When building against older numpy versions (<2), the cpp files are re-cythonized upon install, this requires a working cython installation.
 
 
 ## Contributing

docs/source/_static/shxarraylogo_dark.png

@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- basename | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+

docs/source/_static/shxarraylogo_light.png

@@ -0,0 +1,8 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+

docs/source/_templates/module.rst_t

@@ -4,4 +4,11 @@ API Reference
 .. toctree::
    :maxdepth: 2
 
-   references/shxarray.rst
+   references/shxarray.core.rst
+   references/shxarray.kernels.rst
+   references/shxarray.earth.rst
+   references/shxarray.geom.rst
+   references/shxarray.io.rst
+   references/shxarray.exp.rst
+   references/shxarray.geoslurp.rst
+   references/shxarray.shlib.rst

docs/source/_templates/toc.rst_t

@@ -0,0 +1,24 @@
+Releases
+========
+Change log for shxarray
+
+Last change: |today|
+
+Upcoming Version
+----------------
+- ..
+
+
+Version 1.3.0
+-------------
+- Add logo, favicon and change documentation theme
+- Add `SHtns <https://nschaeff.bitbucket.io/shtns/>`_ as a (very fast) computational backend for analysis and synthesis operations of spherical harmonic data.
+- Fix code such that it can be compiled on Windows with MSVC see: `Installation fails on Windows <https://github.com/ITC-Water-Resources/shxarray/issues/3>`_
+- Add Xarray reading backend to read SINEX files
+- Add option to decorate xarray with user defined attributes which can be saved to file
+- Add a Spectral Sea Level Equation solver
+
+
+Version <= 1.2.0
+----------------
+Consult the `commit messages <https://github.com/ITC-Water-Resources/shxarray/commits/v1.2.0>`_ for information on earlier releases

docs/source/api.rst

@@ -27,7 +27,7 @@
 apidoc_module_dir=os.path.dirname(shxarray.__file__)
 
 apidoc_output_dir = 'references'
-apidoc_separate_modules = False
+apidoc_separate_modules = True
 apidoc_module_first=True
 apidoc_toc_file=False
 
@@ -61,8 +61,7 @@
    ],
    "logo": {
         "alt_text": "shxarray - Home",
-        "text": "shxarray",
-        "image_light": "_static/shxarraylogo_light.png",
+        "image_light": "_static/shxarraylogo_dark.png",
         "image_dark": "_static/shxarraylogo_light.png",
     }
 }

docs/source/changelog.rst

@@ -0,0 +1,23 @@
+Development
+===========
+
+
+Development install
+-------------------
+Users interested in developing can install the latest version from `github <https://github.com/ITC-Water-Resources/shxarray/tree/main>`_. Cython is needed in case the binary extension is being developed, and users can consult the dedicated instructions on the github repository.
+
+
+
+
+Testing suite with pytest
+-------------------------
+From the repositories root directory, the entire test suite can be run with the following command:
+
+.. code-block:: console
+
+   python -m pytest tests/
+
+
+Coding style
+------------
+Code can be supplied with `numpy docstrings <https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html>`_ so they can be parsed into this documentation.

docs/source/conf.py

@@ -15,6 +15,8 @@ Welcome to shxarray's documentation!
    installation.rst
    tutorial.rst
    api.rst
+   dev.rst
+   changelog.rst
 
 Indices and tables
 ==================