DeepLabCut · C-Achard · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 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
@@ -1,37 +1,33 @@
-name: Build dev-docs (mkdocs)
+name: Docs / Build dev-docs
 
 on:
   workflow_call:
     inputs:
       python-version:
-        description: "Python version used to build the dev docs."
+        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 Python
-        uses: actions/setup-python@v6
+      - name: Set up dev-docs environment
+        uses: ./.github/actions/setup-dev-docs
         with:
           python-version: ${{ inputs.python-version }}
 
-      - name: Install system dependencies for mkdocs-material social plugin
-        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
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install ".[dev-docs]"
-
-      - name: Build dev docs
-        run: mkdocs build -v -f dev-docs/mkdocs.yml
+      - name: Build dev-docs
+        run: mkdocs build -v -f ${{ inputs.config-file }}
diff --git a/.github/workflows/build-main-docs.yml b/.github/workflows/build-main-docs.yml
@@ -1,4 +1,4 @@
-name: Build main docs (Jupyter Book)
+name: Docs / Build main docs (Jupyter Book)
 
 on:
   workflow_call:

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,128 @@
+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."
+        required: false
+        default: ""
+        type: string
+
+      default_label:
+        description: "If non-empty, run mike set-default with this label 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 }}
+
+      - 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
@@ -1,4 +1,4 @@
-name: Deploy docs (main + dev-docs latest)
+name: Docs / Deploy docs (main + dev-docs main)
 
 on:
   push:
@@ -7,14 +7,12 @@ on:
 permissions:
   contents: write
 
-# Prevent concurrent deploys to gh-pages; queue new runs instead of cancelling
-# so no push is silently skipped.
 concurrency:
   group: gh-pages-deploy
   cancel-in-progress: false
 
 jobs:
-  build:
+  build-main-docs:
     uses: ./.github/workflows/build-main-docs.yml
     with:
       python-version: "3.10"
@@ -23,10 +21,11 @@ jobs:
     secrets: inherit
 
   deploy-main-docs:
-    needs: build
+    needs: build-main-docs
     runs-on: ubuntu-latest
     permissions:
       contents: write
+
     steps:
       - name: Download built Jupyter Book artifact
         uses: actions/download-artifact@v4
@@ -39,48 +38,17 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: site
-          keep_files: true  # preserve /dev/ versions managed by mike
+          keep_files: true
 
-  deploy-dev-docs-latest:
+  deploy-dev-docs-main:
     needs: deploy-main-docs
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0  # mike needs full history to read/write gh-pages branch
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.10"
-
-      - name: Install system dependencies for mkdocs-material social plugin
-        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
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install ".[dev-docs]"
-
-      - name: Configure git for mike
-        # Sets the commit author identity for the gh-pages branch.
-        # Actual push permission comes from the GITHUB_TOKEN with contents:write above.
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Deploy latest dev-docs with mike (main branch)
-        run: |
-          mike deploy --push \
-            --config-file dev-docs/mkdocs.yml \
-            --deploy-prefix dev \
-            main
-          mike set-default --push \
-            --config-file dev-docs/mkdocs.yml \
-            --deploy-prefix dev \
-            main
+    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:

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: