Add MkDocs documentation site

.github/workflows/cvat2slowfast.yml

@@ -2,6 +2,10 @@ name: Test
 
 on:
   push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - '.github/workflows/cvat2slowfast.yml'
 
 jobs:
   build:

.github/workflows/cvat2ultralytics.yml

@@ -2,6 +2,10 @@ name: Test
 
 on:
   push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - '.github/workflows/cvat2ultralytics.yml'
 
 jobs:
   build:

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,106 @@
+name: Build & Deploy MkDocs (gh-pages with PR previews)
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened, closed]
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+  pages: write
+
+jobs:
+  build:
+    # Run for push, workflow dispatch, PRs from SAME repo that are not closed
+    if: |
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.fork == false &&
+       github.event.action != 'closed')
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install '.[docs]'
+      - name: Build with MkDocs
+        run: mkdocs build
+      - name: Upload built site as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: ./site
+
+  deploy:
+    needs: build
+    # Deploy on push to main (root) or PRs from SAME repo (not closed) -> pr-<N>/
+    if: |
+      github.event_name == 'push' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.fork == false &&
+       github.event.action != 'closed')
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - name: Download built site
+        uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: ./site
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site
+          keep_files: true
+          destination_dir: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || '' }}
+
+  cleanup:
+    # Only when a same-repo PR closes
+    if: >
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.head.repo.fork == false &&
+      github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          fetch-depth: 0
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Remove preview folder
+        shell: bash
+        run: |
+          set -euo pipefail
+          PR_DIR="pr-${{ github.event.number }}"
+          echo "Attempting to remove $PR_DIR"
+          if [ -d "$PR_DIR" ]; then
+            git rm -r "$PR_DIR"
+            git commit -m "Remove preview for PR #${{ github.event.number }}"
+            git push origin gh-pages
+          else
+            echo "No preview folder $PR_DIR found; nothing to do."
+          fi

.github/workflows/detector2cvat.yml

@@ -2,6 +2,10 @@ name: Test
 
 on:
   push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - '.github/workflows/detector2cvat.yml'
 
 jobs:
   build:

.github/workflows/miniscene2behavior.yml

@@ -2,6 +2,10 @@ name: Test
 
 on:
   push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - '.github/workflows/miniscene2behavior.yml'
 
 jobs:
   build:

.github/workflows/player.yml

@@ -2,6 +2,10 @@ name: Test
 
 on:
   push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - '.github/workflows/player.yml'
 
 jobs:
   build:

.github/workflows/tracks_extractor.yml

@@ -2,6 +2,10 @@ name: Test
 
 on:
   push:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - '.github/workflows/tracks_extractor.yml'
 
 jobs:
   build:

.gitignore

@@ -177,18 +177,38 @@ cython_debug/
 # Mac System
 .DS_Store
 
+# Review these for redundancy/excessiveness
 # Tool output
 *.json
 *.xml
 *.jpg
 *.yaml
+!.github/workflows/*.yaml
 *.csv
 *.txt
 
 # Model files
 *.pyth
 *.pyth.zip
 *.yml
+!mkdocs.yml
 
+# data files
+*.xml
+_hugging_face
+_hugging_face
+_hugging_face/*
+
+# Allow CSV files intended to be in docs, ignore one not to include
+!docs/**/*.csv
+docs/methodology_comparison/kabr_dataset/data/consolidated_metadata.csv
+
+helper_scripts/mini-scenes
+
+/methodology_comparison/notes.md
+
+scratchpad*
+
+/kabr-tools/*
 
-helper_scripts/mini-scenes
+.python-version

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Imageomics Institute
+Copyright (c) 2023-2025 Imageomics Institute
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal