Create 2.0 documentation

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+# This file was created automatically with `jupyter-book init --gh-pages` 🪄 💚
+# Ensure your GitHub Pages settings for this repository are set to deploy with **GitHub Actions**.
+
+name: Jupyter Book (via myst) GitHub Pages Deploy
+on:
+  push:
+    # Runs on pushes targeting the default branch
+    branches: [mmaster]
+env:
+  # `BASE_URL` determines, relative to the root of the domain, the URL that your site is served from.
+  # E.g., if your site lives at `https://mydomain.org/myproject`, set `BASE_URL=/myproject`.
+  # If, instead, your site lives at the root of the domain, at `https://mydomain.org`, set `BASE_URL=''`.
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install Jupyter Book (via myst)
+        run: npm install -g jupyter-book
+      - name: Build HTML Assets
+        run: jupyter-book build --html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -113,3 +113,6 @@ venv.bak/
 !dlclivegui/config.py
 # uv package files
 uv.lock
+
+# Built jupyter-book
+docs/_build/

docs/_static/custom.css

@@ -0,0 +1,138 @@
+/* ------------- Header background + text ------------- */
+:root {
+    --dlc-header-bg: rgba(149, 72, 156, 0.85); /* #de6be8 with alpha */
+}
+html.dark {
+      --dlc-header-bg: rgba(69, 83, 100, 0.85);  /* #455364 with alpha */
+}
+/* Header background (frosted) */
+.myst-top-nav {
+  background-color: var(--dlc-header-bg) !important;
+  backdrop-filter: blur(8px) !important;
+  -webkit-backdrop-filter: blur(8px) !important;
+}
+
+/* Dark mode (Tailwind-style: .dark on an ancestor is common in MyST themes) */
+html.dark .myst-top-nav {
+  background-color: var(--dlc-header-bg) !important;
+  backdrop-filter: blur(8px) !important;
+  -webkit-backdrop-filter: blur(8px) !important;
+}
+
+/* Make header links inherit header text color */
+.myst-top-nav a {
+  color: inherit !important;
+}
+
+
+
+/* 1) Keep header as-is; only fix logo container */
+html.dark .myst-top-nav nav a > div {
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+/* Optional: also remove padding/border-radius if the wrapper looks like a badge */
+html.dark .myst-top-nav nav a > div {
+  border: 0 !important;
+}
+
+
+/* =========================================================
+   MyST code blocks (global)
+   Targets the exact structure you pasted:
+   div.myst-code > pre.myst-code-body.hljs > code.language-*
+   ========================================================= */
+
+:root {
+  /* Light mode */
+  --dlc-code-bg: rgba(149, 72, 156, 0.05);
+  --dlc-code-fg: #111827;
+  --dlc-code-border: #e5e7eb;
+  --dlc-code-shadow: 0 1px 3px rgba(0,0,0,0.08);
+
+  /* Accents */
+  --dlc-code-accent: #95489c;
+  --dlc-code-radius: 12px;
+}
+
+html.dark {
+  /* Dark mode */
+  --dlc-code-bg: rgba(69, 83, 100, 0.45);
+  --dlc-code-fg: #e5e7eb;
+  --dlc-code-border: rgba(229,231,235,0.14);
+  --dlc-code-shadow: 0 8px 30px rgba(0,0,0,0.45);
+
+  --dlc-code-accent: #c77dd1;
+}
+
+/* The outer wrapper (controls spacing + frame) */
+.myst-code {
+  border: 1px solid var(--dlc-code-border);
+  border-radius: var(--dlc-code-radius);
+  background: var(--dlc-code-bg);
+  box-shadow: var(--dlc-code-shadow);
+  overflow: hidden; /* makes rounded corners clip */
+}
+
+/* The <pre> element you showed: pre.myst-code-body.hljs */
+.myst-code-body.hljs {
+  background-color: var(--dlc-code-bg) !important; /* overrides inline style "unset" */
+  color: var(--dlc-code-fg) !important;
+
+  margin: 0 !important;
+  padding: 0.9rem 1rem !important;
+  line-height: 1.45;
+  tab-size: 4;
+
+  /* Horizontal scroll for long lines */
+  overflow: auto;
+}
+
+/* Avoid any extra styling on the <code> tag */
+.myst-code-body code {
+  background: transparent !important;
+  color: inherit !important;
+  padding: 0 !important;
+}
+
+/* Base text inside code blocks */
+/* .myst-code-body.hljs {
+  color: var(--dlc-code-fg) !important;
+} */
+
+/* Token colors (HLJS) */
+/* .myst-code-body .hljs-built_in,
+.myst-code-body .hljs-keyword,
+.myst-code-body .hljs-selector-tag,
+.myst-code-body .hljs-literal {
+  color: #95489c;
+}
+
+
+.myst-code-body .hljs-string,
+.myst-code-body .hljs-title,
+.myst-code-body .hljs-attr,
+.myst-code-body .hljs-attribute {
+  color: #059669;
+}
+
+
+
+.myst-code-body .hljs-number,
+.myst-code-body .hljs-symbol,
+.myst-code-body .hljs-bullet {
+  color: #f59e0b;
+}
+
+.myst-code-body .hljs-comment,
+.myst-code-body .hljs-quote {
+  color: rgba(100,116,139,0.85);
+  font-style: italic;
+}
+
+html.dark .myst-code-body .hljs-comment,
+html.dark .myst-code-body .hljs-quote {
+  color: rgba(148,163,184,0.75);
+}
+*/

docs/index.md

@@ -0,0 +1,85 @@
+# DeepLabCut Live GUI
+
+A graphical application for **real-time pose estimation with DeepLabCut** using one or more cameras.
+
+This GUI is designed for **scientists and experimenters** who want to preview, run inference, and record synchronized video with pose overlays—without writing code.
+
+## Table of Contents
+
+:::{toc}
+:::
+
+---
+
+## What this software does
+
+- **Live camera preview** from one or multiple cameras
+- **Real-time pose inference** using DeepLabCut Live models
+- **Multi-camera support** with tiled display
+- **Video recording** (raw or with pose and bounding-box overlays)
+- **Session-based data organization** with reproducible naming
+- **Optional processor plugins** to extend behavior (e.g. remote control, triggers)
+
+The application is built with **PySide6 (Qt)** and is intended for interactive experimental use rather than offline batch processing.
+
+---
+
+## Typical workflow
+
+1. **Install** the application and required camera backends
+2. **Configure cameras** (single or multi-camera)
+3. **Select a DeepLabCut Live model**
+4. **Start preview** and verify frame rate
+5. **Run pose inference** on a selected camera
+6. **Record video** (optionally with overlays)
+7. **Organize results** by session and run
+
+Each of these steps is covered in the *Quickstart* and *User Guide* sections of this documentation.
+
+---
+
+## Who this is for
+
+- Neuroscience and behavior labs
+- Experimentalists running real-time tracking
+- Users who want a **GUI-first** workflow for DeepLabCut Live
+
+You do **not** need to be a software developer to use this tool.
+
+---
+
+## What this documentation covers
+
+- Installation and first-run setup
+- Camera configuration and supported backends
+- Pose inference settings and visualization
+- Recording options and file organization
+- Known limitations of the current release
+
+This documentation intentionally focuses on **end-user operation**.
+Developer-oriented material (APIs, internals, extension points) is out of scope for now.
+
+---
+
+## Current limitations (high-level)
+
+Before getting started, be aware of the following constraints:
+
+- Pose inference runs on **one selected camera at a time** (even in multi-camera mode)
+- Camera synchronization depends on backend capabilities and hardware
+- DeepLabCut Live models must be **exported and compatible** with the selected backend
+- Performance depends on camera resolution, frame rate, GPU availability, and codec choice
+
+A detailed and up-to-date list is maintained in the **Limitations** section.
+
+
+---
+
+## About DeepLabCut Live
+
+DeepLabCut Live enables low-latency, real-time pose estimation using models trained with DeepLabCut.
+This GUI provides an accessible interface on top of that ecosystem for interactive experiments.
+
+---
+
+*This project is under active development. Feedback from real experimental use is highly valued.*

docs/myst.yml

@@ -0,0 +1,50 @@
+# See: https://mystmd.org/guide/frontmatter
+version: 1
+
+project:
+  title: DeepLabCut Live GUI
+  description: PySide6-based GUI for real-time DeepLabCut experiments
+  authors:
+    - name: A. & M. Mathis Labs
+  license: LGPL-3.0
+  github: DeepLabCut/DeepLabCut-live-GUI
+  toc:
+    - file: index.md
+    - title: Quickstart
+      children:
+        - file: quickstart/install
+    - title: User Guide
+      children:
+        - file: user_guide/overview
+      #     - file: quickstart/camera_setup
+      #     - file: quickstart/inference_setup
+      #     - file: quickstart/first_run
+
+      #     - file: user_guide/cameras/index
+      #       children:
+      #         - file: user_guide/cameras/configure_dialog
+      #         - file: user_guide/cameras/supported_backends
+
+      #     - file: user_guide/inference/index
+      #       children:
+      #         - file: user_guide/inference/model_selection
+      #         - file: user_guide/inference/inference_camera
+      #         - file: user_guide/inference/processor_plugins
+
+      #     - file: user_guide/visualization/index
+      #       children:
+      #         - file: user_guide/visualization/preview_and_overlays
+
+      #     - file: user_guide/recording/index
+      #       children:
+      #         - file: user_guide/recording/output_structure
+
+      # - title: Limitations
+      #   children:
+      #     - file: limitations/current_limitations
+
+site:
+  template: book-theme
+  options:
+    logo: _static/images/logo.png
+    style: _static/custom.css