Initial docs setup (#71)

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: 'mambaforge-4.10'
+
+# Build documentation in the doc/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+conda:
+  environment: ci/doc.yml
+python:
+  install:
+    - method: pip
+      path: .

ci/doc.yml

@@ -0,0 +1,14 @@
+name: ndpyramid-docs
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python=3.9
+  - pre-commit
+  - pip
+  - sphinx>=5.0
+  - sphinx-book-theme >= 0.3.0
+  - numpydoc
+  - myst-parser
+  - pip:
+      - -e ..

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,15 @@
+api
+===
+
+.. currentmodule:: ndpyramid
+
+
+Top level API
+~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   pyramid_coarsen
+   pyramid_reproject
+   pyramid_regrid

docs/conf.py

@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+
+import sys
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(os.path.abspath('..'))
+
+print('python exec:', sys.executable)
+print('sys.path:', sys.path)
+
+
+project = 'ndpyramid'
+copyright = '2023, carbonplan'
+author = 'carbonplan'
+release = 'v0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['myst_parser',
+            'sphinx.ext.autodoc',
+            'sphinx.ext.autosummary',]
+
+autosummary_generate = True
+
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# Sphinx project configuration
+source_suffix = ['.rst', '.md']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+
+html_title = 'ndpyarmid'
+html_theme_options = {
+    'logo': {
+        'image_light': '_static/monogram-dark-cropped.png',
+        'image_dark': '_static/monogram-light-cropped.png',
+    }
+}
+html_theme = 'sphinx_book_theme'
+html_title = ''
+repository = 'carbonplan/ndpyarmid'
+repository_url = 'https://github.com/carbonplan/ndpyramid'
+
+html_static_path = ['_static']

docs/generate-pyramids.md

@@ -0,0 +1,25 @@
+# Usage
+
+Ndpyramid provides a set of utilities for creating pyramids with standardized metadata.
+The example below demonstrates the usage of the `pyramid_coarsen` and `pyramid_reproject`
+utilities. Check out [this](https://github.com/carbonplan/ndpyramid/blob/main/notebooks/demo.ipynb)
+Jupyter Notebook for a complete demonstration.
+
+```python
+import xarray as xr
+import rioxarray
+from ndpyramid import pyramid_coarsen, pyramid_reproject
+
+# load a sample xarray.Dataset
+ds = xr.tutorial.load_dataset('air_temperature')
+
+# make a coarsened pyramid
+pyramid = pyramid_coarsen(ds, factors=[16, 8, 4, 3, 2, 1], dims=['lat', 'lon'], boundary='trim')
+
+# make a reprojected (EPSG:3857) pyramid
+ds = ds.rio.write_crs('EPSG:4326')
+pyramid = pyramid_reproject(ds, levels=2)
+
+# write the pyramid to zarr
+pyramid.to_zarr('./path/to/write')
+```

docs/index.rst

@@ -0,0 +1,32 @@
+.. _Intro:
+
+ndpyramid
+---------
+
+A small utility for generating ND array pyramids using Xarray and Zarr.
+
+.. toctree::
+   :hidden:
+   self
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+    :caption: Getting Started
+
+    Quickstart <quick-start>
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+    :caption: Usage
+
+    Generating Pyramids <generate-pyramids>
+
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Reference
+
+    API <api>

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/quick-start.md

@@ -0,0 +1,23 @@
+# Installation
+
+`ndpyramid` can be installed in three ways:
+
+Using the [conda](https://conda.io) package manager that comes with the Anaconda/Miniconda distribution:
+
+```shell
+conda install ndpyramid --channel conda-forge
+```
+
+Using the [pip](https://pypi.org/project/pip/) package manager:
+
+```shell
+python -m pip install ndpyramid
+```
+
+To install a development version from source:
+
+```python
+git clone https://github.com/carbonplan/ndpyramid
+cd ndpyramid
+python -m pip install -e .
+```