DeepLabCut · deruyter92 · Jan 19, 2026 · Jan 19, 2026 · Jan 20, 2026 · May 19, 2026
diff --git a/.github/workflows/build-dev-docs.yml b/.github/workflows/build-dev-docs.yml
@@ -0,0 +1,37 @@
+name: Build dev-docs (mkdocs)
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: "Python version used to build the dev docs."
+        required: false
+        default: "3.10"
+        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
+        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
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: 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/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,78 @@
+name: Deploy docs (main + dev-docs latest)
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    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
+    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  # preserve /dev/ versions managed by mike
+
+  deploy-dev-docs-latest:
+    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
+        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
diff --git a/.github/workflows/intelligent-testing.yml b/.github/workflows/intelligent-testing.yml
@@ -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/manage-dev-docs.yml b/.github/workflows/manage-dev-docs.yml
@@ -0,0 +1,100 @@
+name: Manage dev-docs versions (manual)
+
+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
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-version:
+    if: ${{ inputs.action == 'deploy-version' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate inputs
+        run: |
+          if [ -z "${{ inputs.git_tag }}" ]; then
+            echo "::error::git_tag is required for deploy-version"
+            exit 1
+          fi
+
+      - 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: Check out tagged source tree
+        run: git checkout "${{ inputs.git_tag }}" -- deeplabcut
+
+      - name: Install dev-docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev-docs]"
+
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy version with mike
+        run: |
+          mike deploy --push \
+            --config-file dev-docs/mkdocs.yml \
+            --deploy-prefix dev \
+            "${{ inputs.version_label }}"
+
+  delete-version:
+    if: ${{ inputs.action == 'delete-version' }}
+    runs-on: ubuntu-latest
+    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 dev-docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev-docs]"
+
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Delete version with mike
+        run: |
+          mike delete --push \
+            --config-file dev-docs/mkdocs.yml \
+            --deploy-prefix dev \
+            "${{ inputs.version_label }}"
diff --git a/.github/workflows/publish-book.yml b/.github/workflows/publish-book.yml
diff --git a/_toc.yml b/_toc.yml
@@ -87,6 +87,11 @@ parts:
       - file: docs/benchmark
       - file: docs/recipes/TechHardware
 
+  - caption: Development
+    chapters:
+      - file: docs/dev
+        title: Developer Documentation
+
   - caption: Additional guides (Recipes)
     chapters:
       - file: docs/recipes/index

diff --git a/dev-docs/docs/assets/favicon.ico b/dev-docs/docs/assets/favicon.ico
diff --git a/dev-docs/docs/assets/javascripts/.gitkeep b/dev-docs/docs/assets/javascripts/.gitkeep
diff --git a/dev-docs/docs/assets/logo.png b/dev-docs/docs/assets/logo.png
diff --git a/dev-docs/docs/assets/stylesheets/.gitkeep b/dev-docs/docs/assets/stylesheets/.gitkeep