📝 Initialize Python documentation page (#35)

* ➕ Add jupyter-book

Create beautiful, publication-quality books and documents from computational content!

* 🌱 Initialize Jupyter Book 2 with MyST

Starting with a minimal Jupyter Book initialized with `jupyter book init`. Changed the `myst.yml` to use a proper title and description.

* 📝 Use sphinx-ext-mystmd to generate autodoc API reference

Move myst.yml to docs/ folder, and create a Sphinx configuration file at docs/conf.py. Docs are now built using `cd docs/ && sphinx-build --builder myst . _build/myst-asts && jupyter book start`.

Extensions used:
- `myst_parser` - Because the index page and API docs page in MyST instead of ReST
- `sphinx_ext_mystmd` - Allows Sphinx to build an `api.myst.json` file that can then be used by MyST-MD
- `sphinx.ext.autodoc` - Regular Sphinx extension to pull in documentation from docstrings
- `sphinx.ext.napolean` - Support for NumPy style docstrings

Note: needed to use {eval-rst} directive in API docs because https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#sphinx-ext-autodoc says `sphinx.ext.autodoc` generates ReST only, and I didn't want to use `sphinx-autodoc2`.

* 💬 Indent doctest examples to render them as code blocks

Need to add a sentence, and then indent the code block by 4 spaces to it into a literal block (couldn't figure out syntax highlighting yet). Also taking the chance to properly update the docstrings, mentioning that read_geotiff only supports float32, and documenting the xy_coords method with more details.

* 💚 Don't run rustdoc tests on pyo3 modules

Fixes error with `cargo test` trying to run doctests in src/python/adapters.rs that are meant for Python, not Rust. Xref https://users.rust-lang.org/t/disabling-rustdoc-tests-for-module/50110/2

* 🎨 Use sphinx-ext-mystmd patch to unindent doctest blocks

Figured out how to get doctest_block nodes working with a one-line change at jupyter-book/sphinx-ext-mystmd#2. Partially reverts 5d0ff56.

Author: weiji14

.gitignore

@@ -28,3 +28,6 @@ venv/
 *.egg-info/
 .installed.cfg
 *.egg
+
+# MyST build outputs
+_build

docs/api.md

@@ -0,0 +1,18 @@
+# API Reference
+
+These are the Python docs for `cog3pio`.
+
+## Classes
+
+```{eval-rst}
+.. autoclass:: cog3pio.CogReader
+    :members:
+    :special-members: __dlpack__, __dlpack_device__
+```
+
+
+## Functions
+
+```{eval-rst}
+.. autofunction:: cog3pio.read_geotiff
+```

docs/conf.py

@@ -0,0 +1,17 @@
+# General configurations.
+needs_sphinx = "6.2"
+extensions = [
+    "myst_parser",
+    "sphinx_ext_mystmd",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+# Options for source files.
+exclude_patterns = [
+    "_build",
+]
+# Options for napoleon.
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon
+napoleon_use_admonition_for_examples = True
+napoleon_use_rtype = False
+napoleon_use_ivar = True

docs/index.md

@@ -0,0 +1 @@
+# ⚙️ *cog3pio* - Cloud-optimized GeoTIFF ... Parallel I/O

docs/myst.yml

@@ -0,0 +1,20 @@
+# See docs at: https://mystmd.org/guide/frontmatter
+version: 1
+project:
+  id: 0c0b30a3-67fd-4260-bea5-1d77fb40395d
+  title: "cog3pio"
+  description: "Cloud-optimized GeoTIFF ... Parallel I/O"
+  # keywords: []
+  # authors: []
+  github: https://github.com/weiji14/cog3pio
+  # To autogenerate a Table of Contents, run "jupyter book init --write-toc"
+  toc:
+    # Auto-generated by `myst init --write-toc`
+    - file: index.md
+    - pattern: _build/myst-asts/api.myst.json
+
+site:
+  template: book-theme
+  # options:
+  #   favicon: favicon.ico
+  #   logo: site_logo.png

pyproject.toml

@@ -25,6 +25,13 @@ benchmark = [
     "pytest-codspeed",
     "rioxarray",
 ]
+docs = [
+    "jupyter-book>=2.0.0a0",
+    "myst_parser",
+    "sphinx",
+    # https://github.com/jupyter-book/sphinx-ext-mystmd/pull/2
+    "sphinx-ext-mystmd @ git+https://github.com/weiji14/sphinx-ext-mystmd@e995908b3a898b9c9d5d3fec4ff1478f1f4c1ccd",
+]
 tests = [
     "pytest",
 ]

src/python/adapters.rs

@@ -28,17 +28,19 @@ use crate::io::geotiff::{CogReader, read_geotiff};
 ///
 /// Examples
 /// --------
+/// Read a GeoTIFF from a HTTP url into a numpy.ndarray:
+///
 /// >>> import numpy as np
 /// >>> from cog3pio import CogReader
-/// >>>
-/// >>> reader = CogReader(
-/// >>>     path="https://github.com/rasterio/rasterio/raw/1.3.9/tests/data/float32.tif"
-/// >>> )
-/// >>> array: np.ndarray = reader.data()
+/// ...
+/// >>> cog = CogReader(
+/// ... path="https://github.com/rasterio/rasterio/raw/refs/tags/1.4.3/tests/data/RGBA.uint16.tif"
+/// ...)
+/// >>> array: np.ndarray = np.from_dlpack(cog)
 /// >>> array.shape
-/// >>> (1, 12, 13)
+/// (4, 411, 634)
 /// >>> array.dtype
-/// >>> dtype('float32')
+/// dtype('uint16')
 #[pyclass]
 #[pyo3(name = "CogReader")]
 struct PyCogReader {
@@ -86,7 +88,17 @@ impl PyCogReader {
         (device.device_type as i32, device.device_id)
     }
 
-    /// Get x and y coordinates as numpy.ndarray
+    /// Get list of x and y coordinates.
+    ///
+    /// Determined based on an Affine transformation matrix built from the
+    /// `ModelPixelScaleTag` and `ModelTiepointTag` TIFF tags. Note that non-zero
+    /// rotation (set by `ModelTransformationTag` is currently unsupported.
+    ///
+    /// Returns
+    /// -------
+    /// coords : (np.ndarray, np.ndarray)
+    ///    A tuple (x_coords, y_coords) of np.ndarray objects representing the GeoTIFF's
+    ///    x- and y-coordinates.
     #[allow(clippy::type_complexity)]
     fn xy_coords<'py>(
         &mut self,
@@ -134,7 +146,7 @@ fn path_to_stream(path: &str) -> PyResult<Cursor<Bytes>> {
     Ok(stream)
 }
 
-/// Read a GeoTIFF file from a path on disk or a url into an ndarray
+/// Read a GeoTIFF file from a path on disk or a url into an ndarray.
 ///
 /// Parameters
 /// ----------
@@ -146,12 +158,21 @@ fn path_to_stream(path: &str) -> PyResult<Cursor<Bytes>> {
 /// array : np.ndarray
 ///     3D array of shape (band, height, width) containing the GeoTIFF pixel data.
 ///
+/// Raises
+/// ------
+/// ValueError
+///     If a TIFF which has a non-float32 dtype is passed in. Please use
+///     `cog3pio.CogReader` for reading TIFFs with other dtypes (e.g. uint16).
+///
 /// Examples
 /// --------
-/// from cog3pio import read_geotiff
+/// Read a GeoTIFF from a HTTP url into a numpy.ndarray:
 ///
-/// array = read_geotiff("https://github.com/pka/georaster/raw/v0.1.0/data/tiff/float32.tif")
-/// assert array.shape == (20, 20)
+/// >>> from cog3pio import read_geotiff
+/// ...
+/// >>> array = read_geotiff("https://github.com/pka/georaster/raw/v0.2.0/data/tiff/float32.tif")
+/// >>> array.shape
+/// (1, 20, 20)
 #[pyfunction]
 #[pyo3(name = "read_geotiff")]
 fn read_geotiff_py<'py>(path: &str, py: Python<'py>) -> PyResult<Bound<'py, PyArray3<f32>>> {

src/python/mod.rs

@@ -1,2 +1,3 @@
 /// Adapter interface from Rust to Python
+#[cfg(not(doctest))]
 pub mod adapters;