Fix bugs in docs (#319)

This PR makes several documentation fixes and improvements:

- Updates the docs workflow to use `uv sync` instead of `pip`.
- Fixes broken links on the inference page.
- Adjusts the menu order for better navigation.
- Add more instructions on how to use `uvx`.

Author: gitttt-1234

.github/workflows/docs.yml

@@ -21,23 +21,24 @@ jobs:
       contents: write
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Setup Python
-        uses: actions/setup-python@v4
+      - name: Setup UV
+        uses: astral-sh/setup-uv@v6
         with:
           python-version: "3.12"
 
-      - name: Install sleap-nn with docs dependencies
+      - name: Install dependencies
         run: |
-            pip install -e ".[docs]"
+          uv sync --extra dev --extra torch-cpu --extra docs
 
       - name: Print environment info
         run: |
-            which python
-            pip freeze
+          which python
+          uv pip list
+          uv pip freeze
 
       - name: Setup Git user
         run: |
@@ -49,11 +50,11 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-            mike deploy --update-aliases --allow-empty --push "${{ github.event.release.tag_name }}" latest
+            uv run mike deploy --update-aliases --allow-empty --push "${{ github.event.release.tag_name }}" latest
 
       - name: Build and upload docs (dev)
         if: ${{ github.event_name == 'push' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-            mike deploy --update-aliases --allow-empty --push dev
+            uv run mike deploy --update-aliases --allow-empty --push dev

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Thank you for your interest in contributing to sleap-nn! This guide will help yo
 
 2. **Install sleap-nn dependencies based on your platform**\
 
-   - Sync all dependencies based on your correct wheel using `uv sync`:
+   - Sync all dependencies based on your correct wheel using `uv sync`. `uv sync` creates a `.venv` (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
      - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
 
       ```bash
@@ -28,9 +28,6 @@ Thank you for your interest in contributing to sleap-nn! This guide will help yo
       uv sync --extra dev --extra torch-cpu
       ```
 
-   You can find the correct wheel for your system at:\
-   👉 [https://pytorch.org/get-started/locally](https://pytorch.org/get-started/locally)
-
 
 ## Code Style
 
@@ -108,22 +105,22 @@ cd sleap-nn
 
 2. Install `sleap-nn` with docs dependencies:
    ```bash
-   pip install -e ".[docs]"
+   uv sync --extra docs --extra dev --extra torch-cpu
    ```
 
 3. Build and tag a new documentation version:
    ```bash
-   mike deploy --update-aliases 0.1.4 latest
+   uv run mike deploy --update-aliases 0.1.4 latest
    ```
 
 4. Preview documentation locally:
    ```bash
-   mike serve
+   uv run mike serve
    ```
 
 5. Push a specific version manually:
    ```bash
-   mike deploy --push --update-aliases --allow-empty 0.1.4 latest
+   uv run mike deploy --push --update-aliases --allow-empty 0.1.4 latest
    ```
 
 The documentation is automatically deployed to https://nn.sleap.ai/ when changes are pushed to the main branch or when a new release is published.
@@ -132,7 +129,7 @@ The documentation is automatically deployed to https://nn.sleap.ai/ when changes
 
 1. Create a new branch for your feature or bugfix:
    ```bash
-   git checkout -b feature/your-feature-name
+   git checkout -b your-username/your-feature-name
    ```
 
 2. Make your changes and ensure tests pass

README.md

@@ -3,6 +3,8 @@
 [![CI](https://github.com/talmolab/sleap-nn/actions/workflows/ci.yml/badge.svg)](https://github.com/talmolab/sleap-nn/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/talmolab/sleap-nn/branch/main/graph/badge.svg?token=Sj8kIFl3pi)](https://codecov.io/gh/talmolab/sleap-nn)
 [![Release](https://img.shields.io/github/v/release/talmolab/sleap-nn?label=Latest)](https://github.com/talmolab/sleap-nn/releases/)
+[![PyPI](https://img.shields.io/pypi/v/sleap-nn?label=PyPI)](https://pypi.org/project/sleap-nn)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sleap-nn)
 
 Neural network backend for training and inference for animal pose estimation.
 
@@ -12,28 +14,41 @@ This is the deep learning engine that powers [SLEAP](https://sleap.ai) (Social L
 
 **📚 [Documentation](https://nn.sleap.ai)** - Comprehensive guides and API reference
 
-## Installation
-
-**Prerequisites: Python 3.11**
+## Quick Start
 
-### From PyPI
+Let's start SLEAPiNNg !!! 🐭🐭
 
-- **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
+> For detailed information on setting up config, training/ inference workflows, please refer to our [docs](https://nn.sleap.ai).
 
+#### 1. Install uv
+Install [`uv`](https://github.com/astral-sh/uv) first - a fast Python package manager:
 ```bash
-pip install sleap-nn[torch-cuda118]
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-- **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
+#### 2. Set Up Your Configuration
+
+Create a `config.yaml` file for your experiment.
+
+> Use a sample config from [`docs/sample_configs`](https://github.com/talmolab/sleap-nn/tree/main/docs/sample_configs).
+
+#### 3. Train a model
+
+> Download sample training data from [here](https://storage.googleapis.com/sleap-data/datasets/BermanFlies/random_split1/train.pkg.slp) and validation data from [here](https://storage.googleapis.com/sleap-data/datasets/BermanFlies/random_split1/val.pkg.slp) for quick experimentation.
 
 ```bash
-pip install sleap-nn[torch-cuda128]
+uvx sleap-nn[torch-cpu] train --config-name config.yaml --config-dir /path/to/config_dir/ "data_config.train_labels_path=[labels.pkg.slp]"
 ```
 
-- **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):** 
-Note: Even if torch-cpu is used on macOS, the MPS backend will be available.
+#### 4. Run inference on the trained model
+
+To run inference:
 ```bash
-pip install sleap-nn[torch-cpu]
+uvx sleap-nn[torch-cpu] track --data-path video.mp4 --model-paths model_ckpt_dir/
 ```
 
 
@@ -46,32 +61,37 @@ git clone https://github.com/talmolab/sleap-nn.git
 cd sleap-nn
 ```
 
-2. **Install [`uv`](https://github.com/astral-sh/uv) and development dependencies**  
-   `uv` is a fast and modern package manager for `pyproject.toml`-based projects. Refer [installation docs](https://docs.astral.sh/uv/getting-started/installation/) to install uv.
+2. **Install [`uv`](https://github.com/astral-sh/uv)**
+Install [`uv`](https://github.com/astral-sh/uv) first - a fast Python package manager:
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+  
 
 3. **Install sleap-nn dependencies based on your platform**\
 
-   - Sync all dependencies based on your correct wheel using `uv sync`:
-     - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
-
-      ```bash
-      uv sync --extra dev --extra torch-cuda118
-      ```
+- Sync all dependencies based on your correct wheel using `uv sync`. `uv sync` creates a `.venv` (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
+   - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
 
-      - **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
+   ```bash
+   uv sync --extra dev --extra torch-cuda118
+   ```
 
-      ```bash
-      uv sync --extra dev --extra torch-cuda128
-      ```
-     
-     - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):** 
-     Note: Even if torch-cpu is used on macOS, the MPS backend will be available.
-     ```bash
-      uv sync --extra dev --extra torch-cpu
-      ```
+   - **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
 
-   You can find the correct wheel for your system at:\
-   👉 [https://pytorch.org/get-started/locally](https://pytorch.org/get-started/locally)
+   ```bash
+   uv sync --extra dev --extra torch-cuda128
+   ```
+   
+   - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):** 
+   Note: Even if torch-cpu is used on macOS, the MPS backend will be available.
+   ```bash
+   uv sync --extra dev --extra torch-cpu
+   ```
 
 4. **Run tests**  
    ```bash
@@ -83,30 +103,3 @@ cd sleap-nn
    uv run black --check sleap_nn tests
    uv run ruff check sleap_nn/
    ```
-
-## Quick Start
-
-Let's start SLEAPiNNg !!! 🐭🐭
-
-> For detailed information on setting up config, training/ inference workflows, please refer to our [docs](https://nn.sleap.ai).
-
-#### 1. Set Up Your Configuration
-
-Create a `config.yaml` file for your experiment.
-
-> Use a sample config from [`docs/sample_configs`](https://github.com/talmolab/sleap-nn/tree/main/docs/sample_configs).
-
-#### 2. Train a model
-
-> Download sample training data from [here](https://storage.googleapis.com/sleap-data/datasets/BermanFlies/random_split1/train.pkg.slp) and validation data from [here](https://storage.googleapis.com/sleap-data/datasets/BermanFlies/random_split1/val.pkg.slp) for quick experimentation.
-
-```bash
-sleap-nn train --config-name config.yaml --config-dir configs/ "data_config.train_labels_path=[labels.pkg.slp]"
-```
-
-#### 3. Run inference on the trained model
-
-To run inference:
-```bash
-sleap-nn track --data-path video.mp4 --model-paths model_ckpt_dir/
-```