work on mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,171 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - develop
+    tags:
+      - 'v*'
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  # Job for versioned deployments (runs on develop branch and tags)
+  deploy-versions:
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Important for mike to work with tags
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.5.*" 
+          enable-cache: true
+      - name: Sync
+        run: uv sync  --locked
+
+      - name: Configure Git
+        run: |
+          git config --local user.name "GitHub Actions"
+          git config --local user.email "[email protected]"
+      
+      - name: Deploy docs
+        run: |
+          if [[ $GITHUB_REF == refs/tags/* ]]; then
+            # For tags, deploy the tagged version
+            VERSION=${GITHUB_REF#refs/tags/v}
+            uv run mike deploy --push $VERSION
+            
+            # If this is the latest version, update the 'latest' alias
+            LATEST_TAG=$(git tag --sort=-creatordate | head -n 1)
+            if [[ "v$VERSION" == "$LATEST_TAG" ]]; then
+              uv run mike alias --push $VERSION latest
+              uv run mike set-default --push latest
+            fi
+          else
+            # For develop branch, deploy to 'dev'
+            uv run mike deploy --push --update-aliases dev
+          fi
+
+  # Job for PR previews
+  preview:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.5.*" 
+          enable-cache: true
+      - name: Sync
+        run: uv sync -p 3.11 
+
+      # Only build and deploy if PR is opened/synchronized/reopened
+      - name: Build docs
+        if: github.event.action != 'closed'
+        run: |
+          uv run mkdocs build --site-dir site/pr-${{ github.event.pull_request.number }}
+
+      - name: Deploy preview
+        if: github.event.action != 'closed'
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "[email protected]"
+          
+          # Checkout gh-pages branch
+          git update-index --assume-unchanged uv.lock
+          git fetch origin gh-pages --depth=1
+          git checkout gh-pages
+          
+          # Create preview directory if it doesn't exist
+          mkdir -p pr-previews
+          # Remove old preview if it exists
+          rm -rf pr-previews/pr-${{ github.event.pull_request.number }}
+          # Copy new preview
+          cp -r site/pr-${{ github.event.pull_request.number }} pr-previews/
+          
+          # Commit and push
+          git add pr-previews
+          git commit -m "Deploy preview for PR #${{ github.event.pull_request.number }}"
+          git push origin gh-pages
+
+      - name: Comment on PR
+        if: github.event.action != 'closed'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const preview_url = `https://${context.repo.owner}.github.io/${context.repo.repo}/pr-previews/pr-${context.payload.pull_request.number}/`;
+            github.rest.issues.createComment({
+              issue_number: context.payload.pull_request.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `📚 Documentation preview is ready!\n\nView it here: ${preview_url}`
+            });
+
+      # Cleanup preview when PR is closed
+      - name: Cleanup preview
+        if: github.event.action == 'closed'
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "[email protected]"
+          
+          # Checkout gh-pages branch
+          git fetch origin gh-pages --depth=1
+          git checkout gh-pages
+          
+          # Remove the preview directory for this PR
+          rm -rf pr-previews/pr-${{ github.event.pull_request.number }}
+          
+          # Commit and push if there are changes
+          git add pr-previews
+          git diff --staged --quiet || (git commit -m "Remove preview for PR #${{ github.event.pull_request.number }}" && git push origin gh-pages)
+
+  # Optional job to cleanup old PR previews
+  cleanup-old-previews:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+
+      - name: Get closed PRs
+        id: closed-prs
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const prs = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'closed'
+            });
+            return prs.data.map(pr => pr.number);
+          result-encoding: string
+
+      - name: Cleanup old previews
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "[email protected]"
+          
+          # Get list of preview directories
+          cd pr-previews
+          for preview in pr-*; do
+            if [ -d "$preview" ]; then
+              PR_NUM=$(echo $preview | sed 's/pr-//')
+              if ! echo "${{ steps.closed-prs.outputs.result }}" | grep -q "$PR_NUM"; then
+                rm -rf "$preview"
+                echo "Removed old preview: $preview"
+              fi
+            fi
+          done
+          
+          # Commit and push if there are changes
+          git add .
+          git diff --staged --quiet || (git commit -m "Cleanup old PR previews" && git push origin gh-pages)
+

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.12.1
+    rev: v0.23
     hooks:
       - id: validate-pyproject
 

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/src/examples/HLS_Example.ipynb → docs/examples/rasterio_backend_example.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# TiTiler-CMR: HLS Data Demo\n",
+    "# rasterio backend example: HLS\n",
     "\n",
     "The Harmonized Landsat Sentinel-2 dataset is available in two collections in CMR. This example will use data from the `HLSL30.002` (Landsat) dataset.\n",
     "\n",

docs/src/examples/Timeseries_Example.ipynb → docs/examples/time_series_example.ipynb

@@ -5,8 +5,7 @@
    "id": "d30ab27f-db17-4533-826f-1e514bfca9b5",
    "metadata": {},
    "source": [
-    "# titiler-cmr: timeseries capabilities\n",
-    "\n",
+    "# time series API\n",
     "There is a family of `/timeseries` endpoints in the `titiler.cmr` API that can be used to generate time-aware responses.\n",
     "\n",
     "The Timeseries Extension provides endpoints for requesting results for all points or intervals\n",