deruyter92 · Jul 16, 2026 · Jan 19, 2026 · Jan 19, 2026 · Jan 20, 2026 · May 19, 2026
diff --git a/.github/actions/setup-dev-docs/action.yaml b/.github/actions/setup-dev-docs/action.yaml
@@ -0,0 +1,35 @@
+name: Setup dev-docs environment
+description: Install Python, system deps, and DeepLabCut dev-docs dependencies.
+
+inputs:
+  python-version:
+    description: Python version to use.
+    required: false
+    default: "3.10"
+
+  install-system-deps:
+    description: Install system dependencies required by mkdocs-material social plugin.
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install system dependencies for mkdocs-material social plugin
+      if: ${{ inputs.install-system-deps == 'true' }}
+      shell: bash
+      run: |
+        sudo apt-get update -qq
+        sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev \
+          libjpeg-dev libpng-dev libz-dev
+
+    - name: Install dev-docs dependencies
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install ".[dev-docs]"
diff --git a/.github/workflows/build-dev-docs.yml b/.github/workflows/build-dev-docs.yml
@@ -0,0 +1,33 @@
+name: Docs / Build dev-docs
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: Python version used to build the dev docs.
+        required: false
+        default: "3.10"
+        type: string
+
+      config-file:
+        description: MkDocs config file.
+        required: false
+        default: "dev-docs/mkdocs.yml"
+        type: string
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up dev-docs environment
+        uses: ./.github/actions/setup-dev-docs
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Build dev-docs
+        run: mkdocs build -v -f ${{ inputs.config-file }}
diff --git a/.github/workflows/build-book.yml → .github/workflows/build-main-docs.yml b/.github/workflows/build-book.yml → .github/workflows/build-main-docs.yml
@@ -1,4 +1,4 @@
-name: Build (and optionally deploy) Jupyter Book
+name: Docs / Build main docs (Jupyter Book)
 
 on:
   workflow_call:
@@ -18,8 +18,6 @@ on:
         default: false
         type: boolean
 
-
-
 jobs:
   build:
     runs-on: ubuntu-latest

diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -1,5 +1,5 @@
 ---
-name: Codespell
+name: Code / Codespell
 
 on:
   push:

diff --git a/.github/workflows/deploy-dev-docs-mike.yml b/.github/workflows/deploy-dev-docs-mike.yml
@@ -0,0 +1,129 @@
+name: Docs / Deploy dev-docs with Mike
+
+on:
+  workflow_call:
+    inputs:
+      action:
+        description: "Mike action to perform: deploy or delete."
+        required: true
+        type: string
+
+      version_label:
+        description: "Version label to deploy/delete, e.g. main or 3.0."
+        required: true
+        type: string
+
+      aliases:
+        description: "Space-separated aliases to assign on deploy, e.g. latest-release."
+        required: false
+        default: ""
+        type: string
+
+      default_label:
+        description: "If non-empty, run mike set-default with this label or alias after deploy."
+        required: false
+        default: ""
+        type: string
+
+      git_tag:
+        description: "Optional git tag whose deeplabcut package should be checked out before deploying."
+        required: false
+        default: ""
+        type: string
+
+      python-version:
+        description: Python version used for dev docs.
+        required: false
+        default: "3.10"
+        type: string
+
+      config-file:
+        description: MkDocs config file.
+        required: false
+        default: "dev-docs/mkdocs.yml"
+        type: string
+
+      deploy-prefix:
+        description: Mike deploy prefix.
+        required: false
+        default: "dev"
+        type: string
+
+jobs:
+  mike:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Validate inputs
+        shell: bash
+        run: |
+          case "${{ inputs.action }}" in
+            deploy|delete)
+              ;;
+            *)
+              echo "::error::Unsupported action '${{ inputs.action }}'. Expected 'deploy' or 'delete'."
+              exit 1
+              ;;
+          esac
+
+          if [ "${{ inputs.action }}" = "deploy" ] && [ -z "${{ inputs.git_tag }}" ] && [ "${{ inputs.version_label }}" != "main" ]; then
+            echo "::error::git_tag is required when deploying non-'main' versions."
+            exit 1
+          fi
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Check out tagged package source
+        if: inputs.git_tag != ''
+        shell: bash
+        run: |
+          git checkout "${{ inputs.git_tag }}" -- deeplabcut
+
+      - name: Set up dev-docs environment
+        uses: ./.github/actions/setup-dev-docs
+        with:
+          python-version: ${{ inputs.python-version }}
+          install-system-deps: ${{ inputs.action != 'delete' }}
+
+      - name: Configure git for Mike
+        shell: bash
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy dev-docs version
+        if: inputs.action == 'deploy'
+        shell: bash
+        run: |
+          if [ -n "${{ inputs.aliases }}" ]; then
+            mike deploy --push \
+              --config-file "${{ inputs.config-file }}" \
+              --deploy-prefix "${{ inputs.deploy-prefix }}" \
+              --update-aliases \
+              "${{ inputs.version_label }}" ${{ inputs.aliases }}
+          else
+            mike deploy --push \
+              --config-file "${{ inputs.config-file }}" \
+              --deploy-prefix "${{ inputs.deploy-prefix }}" \
+              "${{ inputs.version_label }}"
+          fi
+
+          if [ -n "${{ inputs.default_label }}" ]; then
+            mike set-default --push \
+              --config-file "${{ inputs.config-file }}" \
+              --deploy-prefix "${{ inputs.deploy-prefix }}" \
+              "${{ inputs.default_label }}"
+          fi
+
+      - name: Delete dev-docs version
+        if: inputs.action == 'delete'
+        shell: bash
+        run: |
+          mike delete --push \
+            --config-file "${{ inputs.config-file }}" \
+            --deploy-prefix "${{ inputs.deploy-prefix }}" \
+            "${{ inputs.version_label }}"
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,54 @@
+name: Docs / Deploy docs (main + dev-docs main)
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  build-main-docs:
+    uses: ./.github/workflows/build-main-docs.yml
+    with:
+      python-version: "3.10"
+      build_dir: "./_build/html"
+      upload_artifact: true
+    secrets: inherit
+
+  deploy-main-docs:
+    needs: build-main-docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download built Jupyter Book artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: built-book
+          path: site
+
+      - name: Deploy main docs to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site
+          keep_files: true
+
+  deploy-dev-docs-main:
+    needs: deploy-main-docs
+    uses: ./.github/workflows/deploy-dev-docs-mike.yml
+    with:
+      action: deploy
+      version_label: main
+      aliases: ""
+      default_label: ""
+      python-version: "3.10"
+      config-file: dev-docs/mkdocs.yml
+      deploy-prefix: dev
+    secrets: inherit
diff --git a/.github/workflows/docs_and_notebooks_checks.yml b/.github/workflows/docs_and_notebooks_checks.yml
@@ -1,4 +1,4 @@
-name: Docs & notebooks freshness and formatting checks
+name: Docs / Docs & notebooks freshness and formatting checks
 
 on:
   pull_request:

diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
@@ -1,4 +1,4 @@
-name: pre-commit (PR only on changed files)
+name: Code / pre-commit (PR only on changed files)
 
 on:
   pull_request:

diff --git a/.github/workflows/intelligent-testing.yml b/.github/workflows/intelligent-testing.yml
@@ -1,4 +1,4 @@
-name: "Intelligent Python Testing"
+name: Code / Intelligent Python Testing
 
 on:
   push:
@@ -76,16 +76,25 @@ jobs:
 
 
   docs:
-    name: Docs build
+    name: Main docs build
     needs: intelligent-test-selection
     if: needs.intelligent-test-selection.outputs.run_docs == 'true'
-    uses: ./.github/workflows/build-book.yml
+    uses: ./.github/workflows/build-main-docs.yml
     with:
       python-version: "3.10"
       build_dir: "./_build/html"
       upload_artifact: false
     secrets: inherit
 
+  dev-docs:
+    name: Dev docs build
+    needs: intelligent-test-selection
+    if: needs.intelligent-test-selection.outputs.run_docs == 'true'
+    uses: ./.github/workflows/build-dev-docs.yml
+    with:
+      python-version: "3.10"
+    secrets: inherit
+
 
   fast-tests:
     name: Fast lane (targeted pytest + selected functional)

diff --git a/.github/workflows/lockfile-check.yml b/.github/workflows/lockfile-check.yml
@@ -1,4 +1,4 @@
-name: Lockfile
+name: Code / Lockfile
 
 on:
   pull_request:

diff --git a/.github/workflows/manage-dev-docs.yml b/.github/workflows/manage-dev-docs.yml
@@ -0,0 +1,61 @@
+name: Docs / Manage dev-docs versions
+
+on:
+  workflow_dispatch:
+    inputs:
+      action:
+        description: "Action to perform"
+        required: true
+        type: choice
+        options:
+          - deploy-version
+          - delete-version
+
+      version_label:
+        description: "Version label to deploy or delete, e.g. 3.0"
+        required: true
+        type: string
+
+      git_tag:
+        description: "Git tag to check out for deploy-version, e.g. v3.0.0rc14. Ignored for delete-version."
+        required: false
+        type: string
+
+      mark_latest_release:
+        description: "Alias this version as latest-release and set /dev/ default to latest-release."
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy-version:
+    if: inputs.action == 'deploy-version'
+    uses: ./.github/workflows/deploy-dev-docs-mike.yml
+    with:
+      action: deploy
+      version_label: ${{ inputs.version_label }}
+      git_tag: ${{ inputs.git_tag }}
+      aliases: ${{ inputs.mark_latest_release && 'latest-release' || '' }}
+      default_label: ${{ inputs.mark_latest_release && 'latest-release' || '' }}
+      python-version: "3.10"
+      config-file: dev-docs/mkdocs.yml
+      deploy-prefix: dev
+    secrets: inherit
+
+  delete-version:
+    if: inputs.action == 'delete-version'
+    uses: ./.github/workflows/deploy-dev-docs-mike.yml
+    with:
+      action: delete
+      version_label: ${{ inputs.version_label }}
+      python-version: "3.10"
+      config-file: dev-docs/mkdocs.yml
+      deploy-prefix: dev
+    secrets: inherit