developmentseed · kylebarron · Feb 10, 2026 · Feb 10, 2026 · Feb 10, 2026 · Feb 10, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -21,9 +21,8 @@ jobs:
         with:
           version: "latest"
 
-      # Ensure docs build without warnings
-      # - name: Check docs
-      #   run: uv run --group docs mkdocs build --strict
+      - name: Ensure docs build without warnings
+        run: uv run --group docs mkdocs build --strict
 
       # Use ruff-action so we get annotations in the Github UI
       - uses: astral-sh/ruff-action@v3

diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml
@@ -1,34 +1,57 @@
-name: Publish docs via GitHub Pages
+name: Publish Python docs
 
+# Only run on new tags starting with `v`
 on:
   push:
-    branches:
-      - main
-    paths:
-      # Only rebuild website when docs have changed
-      - 'README.md'
-      - 'docs/**'
-      - 'mkdocs.yml'
-      - 'rio_stac/**.py'
-      - .github/workflows/deploy_mkdocs.yml
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+# https://stackoverflow.com/a/77412363
+permissions:
+  contents: write
+  pages: write
 
 jobs:
   build:
-    name: Deploy docs
+    name: Deploy Python docs
     runs-on: ubuntu-latest
+    # Used for configuring social plugin in mkdocs.yml
+    # Unclear if this is always set in github actions
+    env:
+      CI: "TRUE"
     steps:
-      - name: Checkout main
-        uses: actions/checkout@v5
+      - 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.12
-        uses: actions/setup-python@v6
+      - uses: astral-sh/setup-uv@v5
         with:
-          python-version: 3.12
+          enable-cache: true
 
-      - name: Install dependencies
+      - name: Deploy docs
+        env:
+          GIT_COMMITTER_NAME: CI
+          GIT_COMMITTER_EMAIL: ci-bot@example.com
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e .["doc"]
+          # 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.
+          VERSION=$(git describe --tags --match="v*" --abbrev=0)
+          echo $VERSION
 
-      - name: Deploy docs
-        run: mkdocs gh-deploy -f docs/mkdocs.yml --force
+          # Only push publish docs as latest version if no letters in git tag
+          # after the first character
+          # (usually the git tag will have v as the first character)
+          # Note the `cut` index is 1-ordered
+          if echo $VERSION | cut -c 2- | grep -q "[A-Za-z]"; then
+            echo "Is beta version"
+            # For beta versions publish but don't set as latest
+            uv run --group docs mike deploy $VERSION --update-aliases --push
+          else
+            echo "Is NOT beta version"
+            uv run --group docs mike deploy $VERSION latest --update-aliases --push
+          fi
diff --git a/CHANGES.md → CHANGELOG.md b/CHANGES.md → CHANGELOG.md
diff --git a/CONTRIBUTING.md → DEVELOP.md b/CONTRIBUTING.md → DEVELOP.md
@@ -23,3 +23,15 @@ This repo is set to use `pre-commit` to run *isort*, *flake8*, *pydocstring*, *b
 ```bash
 $ pre-commit install
 ```
+
+## Documentation
+
+### Building locally
+
+```
+uv run --group docs mkdocs serve
+```
+
+### Publishing docs
+
+Documentation is automatically published when a new tag with `v*` is pushed to `main`. Alternatively, you can manually publish docs by triggering the docs publish workflow from the GitHub actions UI.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/docs/DEVELOP.md b/docs/DEVELOP.md
@@ -0,0 +1 @@
+../DEVELOP.md
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,3 @@
+# API Documentation
+
+::: async_pmtiles
diff --git a/docs/assets/logo_no_text.png b/docs/assets/logo_no_text.png
diff --git a/docs/blog/index.md b/docs/blog/index.md
@@ -0,0 +1,2 @@
+# Blog
+
diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
diff --git a/docs/docs/index.md b/docs/docs/index.md
diff --git a/docs/docs/release-notes.md b/docs/docs/release-notes.md
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -0,0 +1,18 @@
+{% extends "base.html" %}
+
+{% block content %}
+{% if page.nb_url %}
+    <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
+        {% include ".icons/material/download.svg" %}
+    </a>
+{% endif %}
+
+{{ super() }}
+{% endblock content %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}
diff --git a/docs/docs/usage.md → docs/usage.md b/docs/docs/usage.md → docs/usage.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,149 @@
+# Project Information
+site_name: async-pmtiles
+site_description: "Asynchronous PMTiles reader for Python."
+site_author: Development Seed
+
+# Repository
+repo_name: "developmentseed/async-pmtiles"
+repo_url: "http://github.com/developmentseed/async-pmtiles"
+edit_uri: "blob/main/docs/"
+# Note: trailing slash recommended with mike:
+# https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#publishing-a-new-version
+site_url: "https://developmentseed.org/async-pmtiles/"
+docs_dir: docs
+
+# Social links
+extra:
+  social:
+    - icon: "fontawesome/brands/github"
+      link: "https://github.com/developmentseed"
+    - icon: "fontawesome/brands/linkedin"
+      link: "https://www.linkedin.com/company/development-seed"
+  version:
+    alias: true
+    provider: mike
+
+# Layout
+nav:
+  - Home: "index.md"
+  - Usage: "usage.md"
+  - API Reference: "api.md"
+  - Changelog: "CHANGELOG.md"
+  - Contributing: "DEVELOP.md"
+
+watch:
+  - src/
+  - docs/
+  - README.md
+
+theme:
+  language: en
+  name: material
+  custom_dir: docs/overrides
+  logo: assets/logo_no_text.png
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: "red"
+      accent: "light red"
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: "red"
+      accent: "light red"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+  font:
+    text: "Nunito Sans"
+    code: "Fira Code"
+
+  features:
+    - content.code.annotate
+    - content.code.copy
+    - navigation.indexes
+    - navigation.instant
+    - navigation.tracking
+    - search.suggest
+    - search.share
+
+plugins:
+  - autorefs:
+      resolve_closest: true
+  - blog
+  - search
+  - social:
+      enabled: !ENV [CI, false]
+  - mike:
+      alias_type: "copy"
+      canonical_version: "latest"
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_section_style: list
+            docstring_style: google
+            inherited_members: true
+            line_length: 80
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            show_source: false
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            extensions:
+              - griffe_inherited_docstrings
+
+          inventories:
+            - https://affine.readthedocs.io/en/latest/objects.inv
+            - https://developmentseed.org/async-tiff/latest/objects.inv
+            - https://developmentseed.org/morecantile/objects.inv
+            - https://developmentseed.org/obstore/latest/objects.inv
+            - https://docs.python.org/3/objects.inv
+            - https://numpy.org/doc/stable/objects.inv
+            - https://pyproj4.github.io/pyproj/stable/objects.inv
+            - https://rasterio.readthedocs.io/en/stable/objects.inv
+
+# https://github.com/developmentseed/titiler/blob/50934c929cca2fa8d3c408d239015f8da429c6a8/docs/mkdocs.yml#L115-L140
+markdown_extensions:
+  - admonition
+  - attr_list
+  - codehilite:
+      guess_lang: false
+  - def_list
+  - footnotes
+  - md_in_html
+  - pymdownx.arithmatex
+  - pymdownx.betterem
+  - pymdownx.caret:
+      insert: false
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.escapeall:
+      hardbreak: true
+      nbsp: true
+  - pymdownx.magiclink:
+      hide_protocol: true
+      repo_url_shortener: true
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - toc:
+      permalink: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -38,6 +38,18 @@ dev = [
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
 ]
+docs = [
+    # Workaround for https://github.com/mkdocs/mkdocs/issues/4032
+    "click<8.3",
+    "mkdocs-material[imaging]>=9.5.49",
+    "mkdocs>=1.6.1",
+    "mkdocstrings[python]>=1.0",
+    "mike>=2.1.3",
+    "griffe-inherited-docstrings>=1.0.1",
+    # We use ruff format ourselves, but mkdocstrings requires black to be
+    # installed to format signatures in the docs
+    "black>=26",
+]
 
 [tool.ruff]
 select = ["ALL"]