Merge pull request #128 from uw-cryo/docs

Fix RTD Build

Author: scottyhq

.readthedocs.yaml

@@ -12,6 +12,7 @@ build:
     # https://github.com/readthedocs/readthedocs.org/issues/6311...
     install:
       # Install specific pixi environment and list packages
+      - free -h
       - curl -fsSL https://pixi.sh/install.sh | bash
       - $HOME/.pixi/bin/pixi list -e docs
     build:

docs/api.rst

@@ -56,6 +56,7 @@ IO
    xarray.load_neon_dem
    xarray.load_noaa_dem
    xarray.load_ncalm_dem
+   xarray.load_gliht
    download.download_item
    download.read_href
    download.build_usgs_ept_pipeline

docs/conf.py

@@ -1,34 +1,123 @@
 from __future__ import annotations
 
 import importlib.metadata
+import warnings
+
+from sphinx.deprecation import RemovedInSphinx10Warning
+
+# Ignore specific RemovedInSphinx warnings
+warnings.filterwarnings("ignore", category=RemovedInSphinx10Warning)
 
 project = "coincident"
-copyright = "2025, UW TACO Lab"
+copyright = "2026, UW TACO Lab"
 author = "Scott Henderson"
 version = release = importlib.metadata.version("coincident")
 
 # NOTE: it seems order of extensions matters if one depends on another
 extensions = [
-    # "myst_parser",
+    # "myst_parser", # myst-nb includes myst-parser
     "myst_nb",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.mathjax",
+    # "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_design",
 ]
 
+
+# Code block syntax highlighting
+pygments_style = "sphinx"
+
+# Show simplified type names
+typehints_fully_qualified = False
+
+autodoc_type_aliases = {
+    "gpd.GeoDataFrame": "geopandas.GeoDataFrame",
+    "gpd.GeoSeries": "geopandas.GeoSeries",
+    "xr.DataArray": "xarray.DataArray",
+    "xr.Dataset": "xarray.Dataset",
+    "pd.Series": "pandas.Series",
+    "pd.Timestamp": "pandas.Timestamp",
+    "pd.DataFrame": "pandas.DataFrame",
+    "pystac.item_collection.ItemCollection": "pystac.ItemCollection",
+    "pystac_client.client.Client": "pystac_client.Client",
+    "pystac_client.item_search.ItemSearch": "pystac_client.ItemSearch",
+    "arro3.core.Table": "arro3.core.Table",  # don't abbreviate this one
+}
+
+autosummary_generate = True
+autosummary_generate_overwrite = False  # Don't regenerate existing files
+
+# Saves RAM by not importing and inspecting all dependencies!
+autodoc_mock_imports = [
+    # Heavy geospatial libraries with C/C++ extensions
+    "rasterio",  # GDAL wrapper, very memory-intensive
+    "osgeo",  # GDAL Python bindings
+    "gdal",
+    "gdal_array",
+    "pyogrio",  # Fast geospatial I/O
+    # Heavy data processing libraries
+    "odc.stac",  # Open Data Cube STAC loader
+    "xarray",  # Large array operations
+    "rioxarray",  # Rasterio + xarray
+    # Cloud/AWS libraries
+    "boto3",
+    "botocore",
+    "aiobotocore",
+    "s3fs",
+    # Heavy geospatial analysis
+    # "geopandas",  # mocking breaks type hint hyperlinks
+    # "shapely",  # mocking breaks type hint hyperlinks
+    "pyproj",
+    # Specialized data access
+    "sliderule",
+    "maxar_platform",
+    # STAC libraries (less critical but can add up)
+    # NOTE: pystac and pystac_client are needed for intersphinx type linking
+    # "pystac",
+    # "pystac_client",
+    "rustac",
+    "stac_asset",
+    # Arrow ecosystem
+    # "arro3.core", # mocking breaks type hint hyperlinks
+    # "pyarrow", # mocking breaks type hint hyperlinks
+    # Visualization (probably safe to mock for docs)
+    "matplotlib",
+    "contextily",
+    "matplotlib_scalebar",
+    "xyzservices",
+    # Misc heavy dependencies
+    "scipy",
+    "tqdm",
+    "requests",
+]
+
+
+autodoc_preserve_defaults = True
+autodoc_typehints = "description"  # Show type hints in docstring only, not in signature
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": False,  # Skip undocumented members
+    "private-members": False,
+    "special-members": False,
+    "inherited-members": False,  # Don't document inherited members
+    "show-inheritance": False,
+}
+
 source_suffix = {
     ".rst": "restructuredtext",
     ".ipynb": "myst-nb",
     ".md": "myst-nb",
 }
 exclude_patterns = [
     "_build",
+    # "datasets", # UNCOMMENT to temporarily disable executing notebooks
+    # "examples",
     "**.ipynb_checkpoints",
     "Thumbs.db",
     ".DS_Store",
@@ -85,22 +174,25 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
     "geopandas": ("https://geopandas.org/en/latest", None),
     "pystac_client": ("https://pystac-client.readthedocs.io/en/stable", None),
     "pystac": ("https://pystac.readthedocs.io/en/stable", None),
     "stac-asset": ("https://stac-asset.readthedocs.io/en/latest", None),
     "xarray": ("https://docs.xarray.dev/en/stable", None),
+    "arro3": ("https://kylebarron.dev/arro3/latest", None),
 }
 
 nitpick_ignore = [
     ("py:class", "_io.StringIO"),
     ("py:class", "_io.BytesIO"),
 ]
 
-always_document_param_types = True
+# always_document_param_types = True
 # autodoc_typehints = "none"
 nb_execution_mode = "auto"  # off, on
 nb_execution_show_tb = True
 nb_execution_timeout = 90
-nb_execution_allow_errors = False
-# nb_execution_excludepatterns = ["elevation_plotting.ipynb"]
+nb_execution_allow_errors = True
+# NOTE: skip execution of specific notebooks that require large downloads or long processing times
+nb_execution_excludepatterns = ["noaa-coastal-lidar.ipynb"]

docs/datasets/NCALM.ipynb

@@ -87,7 +87,7 @@
    "outputs": [],
    "source": [
     "buffer_size = 0.01\n",
-    "centroid = gf_ncalm.centroid\n",
+    "centroid = gf_ncalm.centroid[0]\n",
     "mini_aoi = gpd.GeoDataFrame(\n",
     "    geometry=[\n",
     "        box(\n",
@@ -111,7 +111,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%%time\n",
     "da_ncalm_dtm = coincident.io.xarray.load_ncalm_dem(\n",
     "    aoi=mini_aoi, product=\"dtm\", dataset_id=gf_ncalm[\"name\"].item()\n",
     ")"
@@ -158,16 +157,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%%time\n",
+    "# Uncomment to download clipped_WALL_GEG_1M_dtm.tif\n",
     "\n",
-    "local_output_dir = \"/tmp/ncalm/\"\n",
+    "# local_output_dir = \"/tmp/ncalm/\"\n",
     "\n",
-    "coincident.io.download.download_ncalm_dem(\n",
-    "    aoi=mini_aoi,\n",
-    "    dataset_id=gf_ncalm[\"name\"].item(),\n",
-    "    product=\"dtm\",\n",
-    "    output_dir=local_output_dir,\n",
-    ")"
+    "# coincident.io.download.download_ncalm_dem(\n",
+    "#     aoi=mini_aoi,\n",
+    "#     dataset_id=gf_ncalm[\"name\"].item(),\n",
+    "#     product=\"dtm\",\n",
+    "#     output_dir=local_output_dir,\n",
+    "# )"
    ]
   },
   {
@@ -185,7 +184,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%%time\n",
     "gf_ncalm_lpc_tiles = coincident.io.download.fetch_lpc_tiles(\n",
     "    aoi=mini_aoi, dataset_id=gf_ncalm.name.item(), provider=\"NCALM\"\n",
     ")"

docs/datasets/noaa-coastal-lidar.ipynb

@@ -64,7 +64,7 @@
    "source": [
     "# Plot the entire footprint for this scene and a subset region\n",
     "buffer_size = 0.02\n",
-    "centroid = gf_noaa.centroid\n",
+    "centroid = gf_noaa.geometry.centroid[0]\n",
     "mini_aoi = gpd.GeoDataFrame(\n",
     "    geometry=[\n",
     "        box(\n",