docs(py): add versioning to py-rattler documentation

.github/workflows/docs.yaml

@@ -4,82 +4,168 @@ on:
   push:
     branches:
       - main
+    tags:
+      - "v*"
+    paths:
+      - "py-rattler/docs/**"
+      - "py-rattler/mkdocs.yml"
+      - "py-rattler/pixi.toml"
+      - "crates/**"
+      - "Cargo.toml"
+      - ".github/workflows/docs.yaml"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "py-rattler/docs/**"
+      - "py-rattler/mkdocs.yml"
+      - "py-rattler/pixi.toml"
+      - ".github/workflows/docs.yaml"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to deploy (e.g. v0.23.0), or leave empty for dev"
+        required: false
+        default: ""
 
 env:
   CARGO_TERM_COLOR: always
   RUSTFLAGS: "-D warnings"
   RUSTDOCFLAGS: --html-in-header header.html
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
-# Allow one concurrent deployment
 concurrency:
   group: "pages"
   cancel-in-progress: true
 
 jobs:
-  build-and-deploy:
-    if: github.repository == 'conda/rattler'
+  build-docs:
+    if: github.repository == 'conda/rattler' && github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           submodules: recursive
-          lfs: false
+
+      - uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
+        with:
+          manifest-path: py-rattler/pixi.toml
+          environments: docs
+
+      - name: Build Py-rattler Documentation
+        run: pixi run --manifest-path py-rattler/pixi.toml build-docs
+
+  docs-release:
+    if: github.repository == 'conda/rattler' && (startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.event.inputs.tag != '' && startsWith(github.event.inputs.tag, 'v')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Checkout tag
+        if: github.event_name == 'workflow_dispatch'
+        run: git checkout tags/${{ github.event.inputs.tag }}
 
       - uses: actions-rs/toolchain@16499b5e05bf2e26879000db0c1d13f7e13fa3af # v1.0.7
         with:
           profile: minimal
 
+      - name: Pre-docs-build
+        run: |
+          echo "<meta name=\"robots\" content=\"noindex\">" > header.html
+
+      - name: Build Rattler Documentation
+        run: cargo doc --workspace --no-deps --all-features --lib
+
       - uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
         with:
           manifest-path: py-rattler/pixi.toml
+          environments: docs
 
-      - name: Setup Pages
-        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+      - name: Configure Git user
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Extract tag name
+        if: github.event_name != 'workflow_dispatch'
+        run: echo "RELEASE_VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+
+      - name: Set version from workflow_dispatch
+        if: github.event_name == 'workflow_dispatch'
+        run: echo "RELEASE_VERSION=${{ github.event.inputs.tag }}" >> $GITHUB_ENV
+
+      - name: Deploy with mike
+        run: pixi run --manifest-path py-rattler/pixi.toml deploy-latest
+
+      - name: Merge rustdoc into gh-pages
+        run: |
+          git clone --branch gh-pages https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git gh-pages-repo
+          cp -r target/doc gh-pages-repo/rattler
+          echo '<meta http-equiv="refresh" content="0; url=rattler/index.html">' > gh-pages-repo/index.html
+          echo "User-Agent: *" > gh-pages-repo/robots.txt
+          echo "Disallow: /" >> gh-pages-repo/robots.txt
+          touch gh-pages-repo/.nojekyll
+          cd gh-pages-repo
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git add .
+          git diff --staged --quiet || (git commit -m "docs: add rustdoc and root redirect" && git push)
+
+  docs-dev:
+    if: github.repository == 'conda/rattler' && (github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && (github.event.inputs.tag == '' || !startsWith(github.event.inputs.tag, 'v'))))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - uses: actions-rs/toolchain@16499b5e05bf2e26879000db0c1d13f7e13fa3af # v1.0.7
+        with:
+          profile: minimal
 
-      #  This does the following:
-      #   - Replaces the docs icon with one that clearly denotes it's not the released package on crates.io
-      #   - Adds a meta tag that forces Google not to index any page on the site.
       - name: Pre-docs-build
         run: |
           echo "<meta name=\"robots\" content=\"noindex\">" > header.html
 
       - name: Build Rattler Documentation
         run: cargo doc --workspace --no-deps --all-features --lib
 
-      - name: Build Py-rattler Documentation
-        run: pixi run --manifest-path py-rattler/pixi.toml build-docs
+      - uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
+        with:
+          manifest-path: py-rattler/pixi.toml
+          environments: docs
 
-      #  This adds the following:
-      #   - A top level redirect to the rattler crate documentation
-      #   - A path to the py-rattler documentation
-      #   - A secondary redirect to the rattler crate documentation
-      #   - A robots.txt file to forbid any crawling of the site (to defer to the docs.rs site on search engines).
-      #   - A .nojekyll file to disable Jekyll GitHub Pages builds.
-      - name: Finalize documentation
+      - name: Configure Git user
         run: |
-          mkdir docs
-          cp target/doc/ docs/rattler -r
-          cp py-rattler/site/  docs/py-rattler -r
-          echo "<meta http-equiv=\"refresh\" content=\"0; url=rattler/index.html\">" > docs/index.html
-          echo "<meta http-equiv=\"refresh\" content=\"0; url=rattler/index.html\">" > docs/rattler/index.html
-          echo "User-Agent: *\nDisallow: /" > docs/robots.txt
-          touch docs/.nojekyll
-
-      # https://github.com/actions/upload-pages-artifact#file-permissions
-      - run: chmod -c -R +rX docs/
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
-        with:
-          path: "docs"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Deploy with mike
+        run: pixi run --manifest-path py-rattler/pixi.toml deploy-dev
 
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+      - name: Merge rustdoc into gh-pages
+        run: |
+          git clone --branch gh-pages https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git gh-pages-repo
+          cp -r target/doc gh-pages-repo/rattler
+          echo '<meta http-equiv="refresh" content="0; url=rattler/index.html">' > gh-pages-repo/index.html
+          echo "User-Agent: *" > gh-pages-repo/robots.txt
+          echo "Disallow: /" >> gh-pages-repo/robots.txt
+          touch gh-pages-repo/.nojekyll
+          cd gh-pages-repo
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git add .
+          git diff --staged --quiet || (git commit -m "docs: add rustdoc and root redirect" && git push)

py-rattler/mkdocs.yml

@@ -162,6 +162,8 @@ nav:
           - TransactionError: transaction_error.md
 
 extra:
+  version:
+    provider: mike
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/prefix-dev
@@ -175,6 +177,8 @@ extra:
       link: https://twitter.com/prefix_dev
 
 plugins:
+  - mike:
+      deploy_prefix: py-rattler
   - mkdocstrings:
       handlers:
         python: