docs, rtd

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3.14"
+  # Overridden to use uv:
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --group docs
+
+sphinx:
+  configuration: "docs/source/conf.py"
+  fail_on_warning: true

docs/source/conf.py

@@ -0,0 +1,119 @@
+# 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 os
+import sys
+
+sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath("../_ext"))
+
+project = "Transformez"
+copyright = "2026, The Continuous-DEMs Development Team."
+author = "Matthew Love"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+nitpicky = True
+nitpick_ignore = [
+    ("py:data", "typing.Union"),
+    ("py:class", "wsgiref.types.WSGIEnvironment"),
+]
+
+extensions = [
+    "sphinx.ext.autodoc",  # Generate docs from docstrings
+    "sphinx.ext.napoleon",  # Support Google-style docstrings
+    "sphinx_autodoc_typehints",  # Generate docs from typehints
+    "sphinx.ext.intersphinx",  # Link to other projects' docs
+    "sphinx.ext.viewcode",  # Add links to source code
+    "sphinx.ext.githubpages",  # Auto-generate .nojekyll for GH Pages
+    "sphinx_argparse_cli",  # argparse
+    "myst_parser",  # Parse Markdown files
+    "module_table",  # Generate module catalog table
+]
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+
+# # MyST Parser configuration
+# source_suffix = {
+#     '.rst': 'restructuredtext',
+#     '.txt': 'markdown',
+#     '.md': 'markdown',
+# }
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pydata_sphinx_theme"
+# html_static_path = ["_static"]
+
+html_sidebars = {
+    "index": [],
+    "modules/*": [],
+}
+
+html_theme_options = {
+    "github_url": "https://github.com/continuous-dems/transformez",
+    "show_prev_next": False,
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    # "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/transformez/",
+            "icon": "fa-solid fa-box",
+        },
+    ],
+    "logo": {
+        "text": "Transformez Documentation",
+    },
+    # "secondary_sidebar_items": [],
+}
+
+# html_context = {
+#     "github_user": "continuous-dems",
+#     "github_repo": "fetchez",
+#     "github_version": "main",
+#     "doc_path": "docs/source",
+# }
+
+# Optional: Add a logo
+# html_logo = "_static/logo.png"
+html_title = "Transformez Documentation"
+# #html_logo = "_static/fetchez_logo_micro.svg"
+html_logo = "_static/continuous_dems_logo_mini.svg"
+
+# -- Autodoc Options ---------------------------------------------------------
+# Ensure methods are documented
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+}
+
+# Combine return description with return type
+napoleon_use_rtype = False
+typehints_use_rtype = False
+
+# Show types of undocumented parameters
+always_document_param_types = True
+
+# Display the parameter's default value alongside the parameter's type
+typehints_defaults = "comma"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
+}

docs/source/index.md

@@ -0,0 +1,113 @@
+# Transformez Documentation
+
+**Transformez** is a standalone Python engine for converting geospatial data between vertical datums (e.g., `MLLW` ↔ `NAVD88` ↔ `Ellipsoid`).
+
+---
+
+![Shift Grid Example](_static/mllw2nvd.png)
+*(Above: A generated vertical shift grid transforming MLLW to NAVD88)*
+
+```transformez run -R loc:"new orleans" -E 3s -I mllw -O 5703```
+
+## Installation
+
+### Prerequisites: HTDP
+Transformez relies on the NGS Horizontal Time-Dependent Positioning (HTDP) software to perform highly accurate plate tectonic and frame transformations. **You must install this separately.**
+
+**For Windows:**
+1. Download the pre-compiled executable (`htdp.exe`) directly from the [NOAA HTDP page](https://geodesy.noaa.gov/TOOLS/Htdp/Htdp.shtml).
+2. Place `htdp.exe` in a directory that is in your system's `PATH` (e.g., `C:\Windows\System32` or a custom scripts folder).
+
+**For Linux / macOS:**
+
+You will need a Fortran compiler (like `gfortran`) to compile the source code.
+
+```bash
+# 1. Download the Fortran source code
+wget https://geodesy.noaa.gov/TOOLS/Htdp/HTDP-download.zip
+unzip HTDP-download.zip
+
+# 2. Compile it
+gfortran -o htdp htdp.f
+
+# 3. Move it to your PATH
+sudo mv htdp /usr/local/bin/
+```
+
+### Install Transformez
+Once HTDP is accessible in your terminal, install the python package:
+
+```bash
+pip install transformez
+```
+
+## Usage
+
+**Generate a vertical shift grid for anywhere on Earth.**
+
+```bash
+# Transform MLLW to WGS84 Ellipsoid in Norton Sound, AK
+
+transformez run -R -166/-164/63/64 -E 1s -I mllw -O 4979
+```
+
+**Transform a raster directly.** Transformez reads the bounds/resolution from the file.
+
+```bash
+transformez run my_dem.tif -I mllw -O 5703
+```
+
+**Integrate directly into your download pipeline.**
+
+```bash
+# Download GEBCO and shift EGM96 to WGS84 on the fly
+fetchez gebco ... --hook transformez:datum_in=5773,datum_out=4979
+```
+
+## Python API
+
+Transformez provides a high-level API for embedding transformations directly into your Python scripts, Jupyter Notebooks, or automated pipelines.
+
+```python
+import transformez
+
+# ---------------------------------------------------------
+# Generate a Shift Grid
+# ---------------------------------------------------------
+# Returns a 2D numpy array. Optionally saves to a file.
+# Requesting "mllw" in India triggers the Global Fallback (FES2014) automatically.
+
+shift_array = transformez.generate_grid(
+    region=[80, 85, 10, 15],  # [West, East, South, North]
+    increment="3s",           # Grid resolution
+    datum_in="mllw",
+    datum_out="4979",         # WGS84 Ellipsoid
+    out_fn="india_shift.tif"  # Optional: Save to disk
+)
+
+# ---------------------------------------------------------
+# Transform an Existing Raster
+# ---------------------------------------------------------
+# Applies the datum shift directly to a DEM and saves the result.
+
+out_file = transformez.transform_raster(
+    input_raster="my_dem_mllw.tif",
+    datum_in="mllw",
+    datum_out="5703:g2012b",  # NAVD88 using specific GEOID12B
+    output_raster="my_dem_navd88.tif"
+)
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: User Guide:
+
+```
+
+Indices and tables
+==================
+
+* {ref}`genindex`
+* {ref}`modindex`
+* {ref}`search`