Migrate to mkdocs for sleap documentation (#2367)

* Modify mkdocs.yml and docs.yml

* Change docs to mkdocs

* Change docs workflow to uv

* Remove path filters

* Fix docs.yml

* Fix docs.yml

* Add branches

* Run with uv

* Fix links

* Fix redirect links

* Fix docs sleap.ai links

* Add API references

* Modify CLI docs

* Modify colab to use sleap-nn and sleap-io

* change: uv installation integration

* change: remove unnecessary warning

* change: comment out conda related setup

* change: remove conda setup steps & replace w/ uv

* fix: add tip to copy entire instance

* fix: additional reminder for pip installation

* fix: add help flag shortcut to train/track

* fix: include yaml config format

* change: add `uv run` reminder & remove deprecated sleap-render args

* Update guides and learnings

* change: update features to include nn and io & uv quick install

* fix: remove deprecated CLI feature desc. from sleap-inspect

* fix: ruff error

* Add note to point to sleap-nn cli

* Update training notebooks

* change: update uv installation instructions for uv tool install/uvx/uv sync

* fix: change quick install to quick start and use uvx

* Add what's new section

* change: typos and moving around info boxes

* change: uv installation steps revamp (platform-specific/installation verification

* Update model evaluation notebook

* fix: reformat tip about uv pip

* fix: highlight use of YAML config

* fix: highlight that uvx is only invocation, not installation

---------

Co-authored-by: AmickL <[email protected]>
Co-authored-by: AmickL <[email protected]>
Co-authored-by: Talmo Pereira <[email protected]>

Author: 3 people

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,34 +1,24 @@
-# Docs build
-name: Docs
+name: Deploy MkDocs to GitHub Pages
 
 on:
-  workflow_dispatch
-#   release:
-#     types:
-#       - published
-#   push:
-#     branches:
-#       - main
-#       - develop
-#     paths:
-#       - "sleap/**"
-#       - "docs/**"
-#       - "mkdocs.yml"
-#       - ".github/workflows/docs.yml"
+  push:
+    branches:
+      - main
+      - develop
+      - divya/change-to-mkdocs
+  workflow_dispatch:  # Allows manual triggering from GitHub UI
 
 jobs:
   docs:
     name: Docs
     runs-on: "ubuntu-latest"
     permissions:
-      # Give the default GITHUB_TOKEN write permission to commit and push the
-      # added or changed files to the repository.
       contents: write
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Fetch all history for all branches
+          fetch-depth: 0
 
       - name: Setup UV
         uses: astral-sh/setup-uv@v6
@@ -37,28 +27,48 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --all-extras
+          uv sync --extra dev --extra nn-cpu --extra docs --extra jupyter
 
       - name: Print environment info
         run: |
-          uv run python --version
-          uv run pip freeze
+          which python
+          uv pip list
+          uv pip freeze
 
       - name: Setup Git user
         run: |
             git config --global user.name "github-actions[bot]"
             git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Build and upload docs (release)
+      - name: Build and upload docs (release event)
         if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-            uv run mike deploy --update-aliases --allow-empty --push "${{ github.event.release.tag_name }}" latest
+          uv runmike deploy --update-aliases --allow-empty --push "${{ github.event.release.tag_name }}" stable
 
-      - name: Build and upload docs (dev)
-        if: ${{ github.event_name == 'push' }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Get tag that 'stable' alias points to, or fallback to 'dev'
+        id: get-stable-tag
         run: |
-            uv run mike deploy --update-aliases --allow-empty --push dev
+          git fetch origin gh-pages || true
+          git checkout origin/gh-pages -- versions.json 2>/dev/null || true
+
+          if [ -f versions.json ]; then
+            stable_tag=$(jq -r '.[] | select(.aliases | index("stable")) | .version' versions.json)
+          fi
+
+          if [ -z "$stable_tag" ]; then
+            echo "No stable alias found. Falling back to 'dev'."
+            stable_tag="dev"
+          fi
+
+          echo "Using: $stable_tag"
+          echo "stable_tag=$stable_tag" >> $GITHUB_OUTPUT
+
+
+      - name: Build and upload docs (push event)
+        if: github.event_name == 'push'
+        run: |
+          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
+            uv run mike deploy --update-aliases --allow-empty --push "${{ steps.get-stable-tag.outputs.stable_tag }}" stable
+          else
+            uv run mike deploy --update-aliases --allow-empty --push dev
+          fi