work on mkdocs

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v3
         with:
-          version: "0.4.22" 
+          version: "0.5.*" 
           enable-cache: true
 
       - name: Set up Python ${{ matrix.python-version }}

.github/workflows/docs.yml

@@ -0,0 +1,207 @@
+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
+          git restore uv.lock
+      
+      - 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 
+          git diff
+
+      # 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
+        id: deploy
+        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 restore 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
+          
+          # Check if there are actual changes in the built site
+          if [ -d "pr-previews/pr-${{ github.event.pull_request.number }}" ]; then
+            diff -r site/pr-${{ github.event.pull_request.number }} pr-previews/pr-${{ github.event.pull_request.number }} > /dev/null 2>&1
+            if [ $? -eq 0 ]; then
+              echo "No changes in documentation. Skipping deployment."
+              exit 0
+            fi
+          fi
+          
+          # 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 }}" || echo "No changes to commit"
+          git diff --staged --quiet || git push origin gh-pages
+          echo "has_changes=true" >> $GITHUB_OUTPUT
+
+      - name: Post/Update PR Review
+        if: github.event.action != 'closed'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const has_changes = '${{ steps.deploy.outputs.has_changes }}' === 'true';
+            const preview_url = `https://${context.repo.owner}.github.io/${context.repo.repo}/pr-previews/pr-${context.payload.pull_request.number}/`;
+            const message = `📚 Documentation preview will be available at: ${preview_url}
+
+            Status: ${has_changes ? '✅ Preview is ready!' : '🔄 No changes in documentation since last update'}`;
+            
+            const reviews = await github.rest.pulls.listReviews({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number,
+            });
+            
+            const docReview = reviews.data.find(review => 
+              review.user.login === 'github-actions[bot]' && 
+              review.body.includes('Documentation preview will be available at:')
+            );
+            
+            if (!docReview) {
+              await github.rest.pulls.createReview({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.pull_request.number,
+                body: message,
+                event: 'COMMENT'
+              });
+            }
+
+      - 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 restore uv.lock
+          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@v7
+        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",