[skip ci] 📝 Add CudaCogReader class to API docs

Need to include 'cuda' feature flag to maturin on ReadtheDocs, and get libnvtiff-dev from conda-forge. Added a warning to the docstring indicating that CudaCogReader is experimental, and only available on linux-x86_64 and linux-aarch64 builds.

Author: weiji14

docs/.readthedocs.yaml

@@ -9,11 +9,19 @@ build:
   os: "ubuntu-24.04"
   tools:
     nodejs: "23"
-    python: "3.12"
+    python: "mambaforge-23.11"
     rust: "1.86"
   jobs:
+    pre_install:
+      # Patch nvtiff.h (v0.5.0) to remove default arguments and missing enum tag
+      - export CONDA_PREFIX="$CONDA_ENVS_PATH/$CONDA_DEFAULT_ENV";
+        unset CONDA_DEFAULT_ENV;
+        mamba list;
+        sed --in-place "s/memLimit=0/memLimit/g" $CONDA_PREFIX/include/nvtiff.h;
+        sed --in-place "s/stream=0/stream/g" $CONDA_PREFIX/include/nvtiff.h;
+        sed --in-place "s/nvtiffTagDataType type/enum nvtiffTagDataType type/g" $CONDA_PREFIX/include/nvtiff.h;
     install:
-      - pip install .[docs]
+      - MATURIN_PEP517_ARGS="--features cuda,pyo3" pip install .[docs]
       # https://github.com/jupyter-book/sphinx-ext-mystmd/pull/2
       - pip install --ignore-installed git+https://github.com/weiji14/sphinx-ext-mystmd@e995908b3a898b9c9d5d3fec4ff1478f1f4c1ccd
       - pip list
@@ -29,3 +37,6 @@ build:
     post_build:
       - "mkdir --parents $READTHEDOCS_OUTPUT/html/"
       - "mv docs/_build/html/* $READTHEDOCS_OUTPUT/html/"
+
+conda:
+  environment: docs/environment.yml

docs/api.md

@@ -9,6 +9,9 @@ These are the Python docs for `cog3pio`, for the Rust docs, see
 .. autoclass:: cog3pio.CogReader
     :members:
     :special-members: __dlpack__, __dlpack_device__
+.. autoclass:: cog3pio.CudaCogReader
+    :members:
+    :special-members: __dlpack__, __dlpack_device__
 ```
 
 ## Xarray

docs/environment.yml

@@ -0,0 +1,7 @@
+name: cog3pio
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python=3.12
+  - libnvtiff-dev=0.5.0

src/python/cudacog.rs

@@ -13,6 +13,11 @@ use crate::python::adapters::path_to_stream;
 
 /// Python class interface to a Cloud-optimized GeoTIFF reader (nvTIFF backend).
 ///
+/// Warning
+/// -------
+/// This is an experimental feature only enabled on linux-x86_64 and linux-aarch64
+/// wheel builds.
+///
 /// Parameters
 /// ----------
 /// path : str
@@ -23,6 +28,13 @@ use crate::python::adapters::path_to_stream;
 /// reader : cog3pio.CudaCogReader
 ///     A new CudaCogReader instance for decoding GeoTIFF files.
 ///
+/// Raises
+/// ------
+/// ImportError
+///     If ``nvTIFF`` is not installed. Please install it (e.g. via
+///     ``apt install nvtiff-cuda-12`` or ``dnf install nvtiff-cuda-12``) before using
+///     this class.
+///
 /// Examples
 /// --------
 /// Read a GeoTIFF from a HTTP url into a DLPack tensor: