Skip to content

Commit 970d07d

Browse files
BSchilperoortBSchilperoort
authored
Add user documentation (#40)
* Add user documentation, move notebooks into docs * Point to the right path for package version * Move RTD config to docs folder * Change extension of rtd config to yaml * Add links to API reference, improve quickstart * Revert changes to __init__ * Fix test data paths * Update the changelog * Apply new ruff formatting * Update for numpy 2.0 compatibility * Add cftime to dev dependencies (for loading test data)
1 parent c143aaf commit 970d07d

34 files changed

+360
-26
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ coverage.xml
1818
.tox
1919

2020
docs/_build
21+
docs/generated
2122

2223
# ide
2324
.idea

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
66

77
## Unreleased
88

9+
Added:
10+
- Documentation for the package, including readthedocs integration ([#40](https://github.com/EXCITED-CO2/xarray-regrid/pull/40)).
911

1012
## v0.2.3 (2024-02-29)
1113

‎docs/.readthedocs.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
version: 2
2+
3+
build:
4+
os: ubuntu-22.04
5+
tools:
6+
python: "3.11"
7+
8+
sphinx:
9+
configuration: docs/conf.py
10+
11+
python:
12+
install:
13+
- method: pip
14+
path: .
15+
extra_requirements:
16+
- docs

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = xarray-regrid
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/changelog_link.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. include:: ../CHANGELOG.md
2+
:parser: myst_parser.sphinx_

‎docs/conf.py‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
#
7+
8+
import datetime
9+
from importlib.metadata import version as get_version
10+
11+
# -- Path setup --------------------------------------------------------------
12+
13+
# If extensions (or modules to document with autodoc) are in another directory,
14+
# add these directories to sys.path here. If the directory is relative to the
15+
# documentation root, use os.path.abspath to make it absolute, like shown here.
16+
#
17+
# import os
18+
# import sys
19+
# sys.path.insert(0, os.path.abspath('.'))
20+
21+
# General information about the project.
22+
project = "xarray-regrid"
23+
current_year = datetime.datetime.now().year
24+
copyright = f"2023-{current_year}, Bart Schilperoort"
25+
author = "Bart Schilperoort"
26+
27+
# The version info for the project you're documenting, acts as replacement for
28+
# |version| and |release|, also used in various other places throughout the
29+
# built documents.
30+
31+
# The version info for the project you're documenting, acts as replacement for
32+
# |version| and |release|, also used in various other places throughout the
33+
# built documents.
34+
# The short X.Y version.
35+
version = get_version("xarray_regrid").split("+")[0]
36+
# The full version, including alpha/beta/rc tags.
37+
release = get_version("xarray_regrid")
38+
39+
# -- General configuration ------------------------------------------------
40+
41+
# Add any Sphinx extension module names here, as strings. They can be
42+
# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
43+
# ones.
44+
extensions = [
45+
"sphinx.ext.autodoc",
46+
"sphinx.ext.coverage",
47+
"sphinx.ext.doctest",
48+
"sphinx.ext.intersphinx",
49+
"sphinx.ext.mathjax",
50+
"sphinx.ext.napoleon",
51+
"sphinx.ext.todo",
52+
"sphinx.ext.viewcode",
53+
"autoapi.extension",
54+
#"myst_parser",
55+
"myst_nb",
56+
]
57+
58+
extlinks = {
59+
"issue": ("https://github.com/excited-CO2/xarray-regrid/issues/%s", "GH#%s"),
60+
"pr": ("https://github.com/excited-CO2/xarray-regrid/pull/%s", "PR#%s"),
61+
}
62+
63+
# Add any paths that contain templates here, relative to this directory.
64+
templates_path = ["_templates"]
65+
66+
# List of patterns, relative to source directory, that match files and
67+
# directories to ignore when looking for source files.
68+
# This patterns also effect to html_static_path and html_extra_path
69+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "data"]
70+
71+
# If true, `todo` and `todoList` produce output, else they produce nothing.
72+
todo_include_todos = False
73+
74+
# Myst_nb options
75+
nb_execution_mode = "off"
76+
77+
# -- Use autoapi.extension to run sphinx-apidoc -------
78+
79+
autoapi_dirs = ["../src"]
80+
81+
# -- Options for HTML output ----------------------------------------------
82+
83+
# The theme to use for HTML and HTML Help pages. See the documentation for
84+
# a list of builtin themes.
85+
#
86+
html_theme = "sphinx_rtd_theme"
87+
88+
# Theme options are theme-specific and customize the look and feel of a theme
89+
# further. For a list of options available for each theme, see the
90+
# documentation.
91+
#
92+
# html_theme_options = {}
93+
94+
# Custom sidebar templates, must be a dictionary that maps document names
95+
# to template names.
96+
#
97+
# This is required for the alabaster theme
98+
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
99+
html_sidebars = {
100+
"**": [
101+
"globaltoc.html",
102+
"relations.html", # needs 'show_related': True theme option to display
103+
"searchbox.html",
104+
]
105+
}
106+
107+
html_logo = "./assets/logo.png"
108+
109+
# -- Options for Intersphinx
110+
111+
intersphinx_mapping = {
112+
"python": ("https://docs.python.org/3", None),
113+
"numpy": ("https://numpy.org/doc/stable/", None),
114+
"xarray": ("https://docs.xarray.dev/en/stable/", None),
115+
}

‎docs/getting_started.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Quickstart
2+
==========
3+
4+
``xarray-regrid`` allows you to regrid xarray Datasets or DataArrays to a new resolution.
5+
You can install xarray-regrid with pip:
6+
7+
.. code:: shell
8+
9+
pip install xarray-regrid
10+
11+
12+
To use the package, import ``xarray_regrid``. This will register the ``.regrid`` 'accessor' so it can be used.
13+
Next load in the data you want to regrid, and the data with a grid you want to regrid to:
14+
15+
.. code:: python
16+
17+
import xarray_regrid
18+
import xarray
19+
20+
ds = xr.open_dataset("input_data.nc")
21+
ds_grid = xr.open_dataset("target_grid.nc")
22+
23+
ds = ds.regrid.linear(ds_grid)
24+
25+
# or, for example:
26+
ds = ds.regrid.conservative(ds_grid, latitude_coord="lat")
27+
28+
29+
Multiple regridding methods are available:
30+
31+
* `linear interpolation <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.linear>`_ (``.regrid.linear``)
32+
* `nearest-neighbor <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative>`_ (``.regrid.nearest``)
33+
* `cubic interpolation <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.cubic>`_ (``.regrid.cubic``)
34+
* `conservative regridding <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative>`_ (``.regrid.conservative``)
35+
36+
Additionally, a zonal statistics `method to compute the most common value <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.most_common>`_
37+
is available (``.regrid.most_common``).
38+
This can be used to upscale very fine categorical data to a more course resolution.

‎docs/index.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
.. toctree::
2+
:maxdepth: 3
3+
:hidden:
4+
5+
self
6+
7+
8+
.. toctree::
9+
:maxdepth: 3
10+
:caption: User Guide
11+
:hidden:
12+
13+
Quickstart <getting_started>
14+
Example Notebooks <notebooks/index>
15+
16+
17+
.. toctree::
18+
:maxdepth: 3
19+
:caption: Technical information
20+
:hidden:
21+
22+
Changelog <changelog_link>
23+
24+
xarray-regrid: Regridding utilities for xarray
25+
**********************************************
26+
27+
|PyPI| |DOI|
28+
29+
Overview
30+
========
31+
32+
``xarray-regrid`` extends xarray with regridding methods, making it possibly to easily and effiently regrid between two rectilinear grids.
33+
34+
The following methods are supported:
35+
36+
* `Linear <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.linear>`_
37+
* `Nearest-neighbor <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.nearest>`_
38+
* `Conservative <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative>`_
39+
* `Cubic <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.cubic>`_
40+
* `"Most common value" (zonal statistics) <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.most_common>`_
41+
42+
Note that "Most common value" is designed to regrid categorical data to a coarse resolution. For regridding categorical data to a finer resolution, please use "nearest-neighbor" regridder.
43+
44+
For usage examples, please refer to the `quickstart guide <getting_started>`_ and the `example notebooks <notebooks/index>`_.
45+
46+
Installing
47+
==========
48+
49+
.. code:: shell
50+
51+
pip install xarray-regrid
52+
53+
54+
Acknowledgements
55+
================
56+
57+
This package was developed under Netherlands eScience Center grant `NLESC.OEC.2022.017 <https://research-software-directory.org/projects/excited>`_.
58+
59+
Some methods were inspired by discussions in the `Pangeo <https://pangeo.io>`_ community.
60+
61+
.. |PyPI| image:: https://img.shields.io/pypi/v/xarray-regrid.svg?style=flat
62+
:target: https://pypi.python.org/pypi/xarray-regrid/
63+
64+
.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.10203304.svg
65+
:target: https://doi.org/10.5281/zenodo.10203304

‎docs/make.bat‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
set SPHINXPROJ=xarray-regrid
13+
14+
if "%1" == "" goto help
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
20+
echo.installed, then set the SPHINXBUILD environment variable to point
21+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
22+
echo.may add the Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

0 commit comments

Comments
 (0)