From 43dcf67ac8037d36adc4aa57d38f10f9661d8baa Mon Sep 17 00:00:00 2001
From: Kyle Barron <kylebarron2@gmail.com>
Date: Mon, 1 Jan 2024 18:12:38 -0500
Subject: [PATCH] Publish python docs (#372)

---
 .github/workflows/python-docs.yml | 68 +++++++++++++++++++++++++++++++
 README.md                         |  7 ++--
 python/.gitignore                 |  3 +-
 python/core/DEVELOP.md            | 25 ++++++++++++
 python/core/README.md             | 12 +++++-
 5 files changed, 109 insertions(+), 6 deletions(-)
 create mode 100644 .github/workflows/python-docs.yml
 create mode 100644 python/core/DEVELOP.md

diff --git a/.github/workflows/python-docs.yml b/.github/workflows/python-docs.yml
new file mode 100644
index 000000000..4355fbfc4
--- /dev/null
+++ b/.github/workflows/python-docs.yml
@@ -0,0 +1,68 @@
+name: Publish Python docs via GitHub Pages
+
+# Only run on new tags starting with `py-v`
+on:
+  push:
+    tags:
+      - 'py-v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Deploy Python core docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: python/core/
+    steps:
+      - uses: actions/checkout@v4
+        # We need to additionally fetch the gh-pages branch for mike deploy
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.11
+        id: setup-python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install and configure Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.7.1
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v3
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Install root project
+        run: poetry install --no-interaction
+
+      - name: Deploy docs
+        env:
+          GIT_COMMITTER_NAME: CI
+          GIT_COMMITTER_EMAIL: ci-bot@example.com
+        run: |
+          # Get most recent git tag
+          # https://stackoverflow.com/a/7261049
+          # https://stackoverflow.com/a/3867811
+          # We don't use {{github.ref_name}} because if triggered manually, it
+          # will be a branch name instead of a tag version.
+          # Then remove `py-` from the tag
+          VERSION=$(git describe --tags --match="py-*" --abbrev=0 | cut -c 4-)
+
+          # Only push docs if no letters in git tag after the first character
+          # (usually the git tag will have v as the first character)
+          if ! echo $VERSION | cut -c 1- | grep -q "[A-Za-z]"; then
+            poetry run mike deploy $VERSION latest --update-aliases --push
+          fi
diff --git a/README.md b/README.md
index efd413aee..ab9aeae81 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,10 @@ This repository also includes [Python bindings](https://github.com/kylebarron/ge
 
 ## Documentation
 
-- Rust library <https://docs.rs/geoarrow2/latest/geoarrow2/>
-- JavaScript library: <https://geoarrow.github.io/geoarrow-rs/js/>
-- Rust wasm-bindgen library: <https://docs.rs/geoarrow-wasm/latest/geoarrow_wasm/>
+- [Use from Rust](https://docs.rs/geoarrow2/latest/geoarrow2/)
+- [Use from Python](https://geoarrow.github.io/geoarrow-rs/python/core)
+- [Use from JavaScript](https://geoarrow.github.io/geoarrow-rs/js)
+- [Create your own Rust-JavaScript library with `wasm-bindgen`](https://docs.rs/geoarrow-wasm/latest/geoarrow_wasm/)
 
 ## Examples
 
diff --git a/python/.gitignore b/python/.gitignore
index af3ca5ef1..75304478b 100644
--- a/python/.gitignore
+++ b/python/.gitignore
@@ -1,3 +1,4 @@
+site
 /target
 
 # Byte-compiled / optimized / DLL files
@@ -69,4 +70,4 @@ docs/_build/
 .vscode/
 
 # Pyenv
-.python-version
\ No newline at end of file
+.python-version
diff --git a/python/core/DEVELOP.md b/python/core/DEVELOP.md
new file mode 100644
index 000000000..c82efc99e
--- /dev/null
+++ b/python/core/DEVELOP.md
@@ -0,0 +1,25 @@
+# Develop Docs
+
+## Docs
+
+View docs:
+
+```
+poetry run mkdocs serve
+```
+
+Deploy docs (automatically):
+
+Push a new tag with the format `py-v*`, such as `py-v0.1.0`.
+
+Deploy docs (manually):
+
+```
+poetry run mike deploy VERSION_TAG --update-aliases --push --deploy-prefix python/core/
+```
+
+This only needs to be run once ever, to set the redirect from `https://geoarrow.github.io/geoarrow-rs/python/core/` to `https://geoarrow.github.io/geoarrow-rs/python/core/latest/`.
+
+```
+poetry run mike set-default latest --deploy-prefix python/core/ --push
+```
diff --git a/python/core/README.md b/python/core/README.md
index 0c1eff938..950dbe963 100644
--- a/python/core/README.md
+++ b/python/core/README.md
@@ -1,5 +1,7 @@
 # `geoarrow.rust.core`: Python bindings to `geoarrow-rs`
 
+## Overview
+
 This library contains Python bindings to the [GeoArrow Rust implementation](https://github.com/geoarrow/geoarrow-rs).
 
 - **Fast**: Connects to algorithms implemented in [GeoRust](https://georust.org/), which compile to native code.
@@ -7,7 +9,7 @@ This library contains Python bindings to the [GeoArrow Rust implementation](http
 - **Self-contained**: Zero Python dependencies.
 - **Easy to install**: Distributed as static binary wheels with zero C dependencies.
 - **Strong, static typing**: geometry arrays have a known type
-- **Interoperable ecosystem**: Data can be shared at zero cost with other libraries in the burgeoning [GeoArrow ecosystem](https://geoarrow.org/), such as [geoarrow-c](https://github.com/geoarrow/geoarrow-c/tree/main/python) or [lightning-fast map rendering](https://github.com/developmentseed/lonboard).
+- **Interoperable ecosystem**: Data is shared at zero cost with other Python libraries in the burgeoning [GeoArrow ecosystem](https://geoarrow.org/), such as [geoarrow-c](https://github.com/geoarrow/geoarrow-c/tree/main/python) or [lightning-fast map rendering](https://github.com/developmentseed/lonboard).
 
 More specifically, it contains:
 
@@ -17,9 +19,15 @@ More specifically, it contains:
 - Rust-based algorithms for computations on GeoArrow memory.
 - Rust-based parsers for various geospatial file formats.
 
-Future work:
+## Documentation
+
+Refer to the documentation at [geoarrow.github.io/geoarrow-rs/python/core](https://geoarrow.github.io/geoarrow-rs/python/core).
+
+## Future work:
 
 - [ ] 3D coordinates. Only 2D geometries are supported at this time.
 - [ ] CRS management. This currently loses the CRS information in the [GeoArrow metadata](https://geoarrow.org/extension-types#extension-metadata).
 
+## Background reading
+
 Refer to the [GeoArrow Python module proposal](https://github.com/geoarrow/geoarrow-python/issues/38) for more background information.