DOCS: Sets up docs for Squirrel

.github/workflows/gh-pages.yml

@@ -0,0 +1,64 @@
+# This workflow will publish a new version of the documentation to the gh-pages branch
+
+name: Build & Deploy Documentation
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "mkdocs.yml"
+      - "docs/**"
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Important for MkDocs to access commit history
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: 'docs-requirements.txt'
+
+      - name: Install dependencies
+        run: |
+          pip install -r docs-requirements.txt
+
+      - name: Build Docs
+        run: mkdocs build --strict --verbose
+
+      - name: Upload Built Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: built-docs
+          path: ./site
+
+  deploy:
+    needs: build  # Ensures that the deploy step only runs after the build
+    if: github.event_name == 'push'  # Only run deploy on push events
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download Built Docs
+        uses: actions/download-artifact@v4
+        with:
+          name: built-docs
+          path: ./site
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

.gitignore

@@ -62,3 +62,6 @@ Thumbs.db
 # Logs
 logs/
 *.log
+
+# MkDocs
+site/

README.md

@@ -1,8 +1,8 @@
-# React Squirrel
+# Squirrel
 
-Modern web-based frontend for Configuration Management of EPICS Process Variables (PVs).
+A web-based application for configuration management of EPICS Process Variables (PVs).
 
-React Squirrel provides a responsive, high-performance interface for creating snapshots of control system states, comparing configurations, and managing PV settings. It communicates with a backend API (score-backend) that handles persistence and EPICS control system integration.
+Squirrel provides a responsive, high-performance interface for creating snapshots of control system states, comparing configurations, and managing PV settings. It communicates with a backend API (score-backend) that handles persistence and EPICS control system integration.
 
 ## Features
 

docs-requirements.txt

@@ -0,0 +1,4 @@
+mkdocs
+mkdocs-material
+mkdocs-git-revision-date-localized-plugin
+mkdocs-git-committers-plugin-2

docs/getting-started.md

@@ -0,0 +1,47 @@
+# Getting Started
+
+This guide will help you get up and running with Squirrel.
+
+## Prerequisites
+
+Before using Squirrel, ensure:
+
+1. The **backend API** (squirrel backend) is running and accessible
+2. You have a modern web browser (Chrome, Firefox, Edge, or Safari)
+3. Network access to your EPICS control system (for live values)
+
+## Accessing the Application
+
+Open your web browser and navigate to the Squirrel URL provided by your administrator.
+
+## User Interface Overview
+
+Squirrel has a simple, consistent layout:
+
+<!-- TODO: Add screenshot: images/main-interface.png -->
+
+### Sidebar Navigation
+
+The left sidebar provides access to all main features:
+
+- **Snapshots** - View and manage saved snapshots
+- **PV Browser** - Browse and search for PVs
+- **Tags** - Manage tag groups for organizing PVs
+
+### Main Content Area
+
+The main area displays the content for the selected feature. Most views include:
+
+- **Search bar** - Filter items by name or other criteria
+- **Action buttons** - Create, delete, or perform operations
+- **Data table** - View and interact with data
+
+### Admin Mode
+
+Some features require admin privileges. If you have admin access, you can toggle admin mode using the switch in the sidebar.
+
+## Next Steps
+
+- Learn about [Snapshots](user-guide/snapshots.md) - the core feature for saving PV states
+- Explore the [PV Browser](user-guide/pv-browser.md) to find and manage PVs
+- Set up [Tags](user-guide/tags.md) to organize your PVs

docs/images/.gitkeep

@@ -0,0 +1,14 @@
+# Placeholder for screenshot images
+# Add screenshots here with the following names:
+# - main-interface.png
+# - snapshot-list.png
+# - create-snapshot-dialog.png
+# - snapshot-details.png
+# - snapshot-comparison.png
+# - pv-browser.png
+# - csv-import-dialog.png
+# - pv-details.png
+# - tags-page.png
+# - create-tag-group.png
+# - restore-button.png
+# - restore-dialog.png

docs/index.md

@@ -0,0 +1,30 @@
+# Squirrel
+
+Welcome to the Squirrel user guide. Squirrel application for configuration management of EPICS Process Variables (PVs).
+
+![squirrel](images/home.png)
+
+## What is Squirrel?
+
+Squirrel provides a responsive interface for:
+
+- **Creating snapshots** of control system states
+- **Comparing configurations** between different points in time
+- **Restoring values** to return systems to known states
+
+## Key Features
+
+| Feature                   | Description                                                |
+| ------------------------- | ---------------------------------------------------------- |
+| **Snapshot Management**   | Create, view, and delete snapshots of PV values            |
+| **Live PV Values**        | Real-time display of current values alongside saved values |
+| **Snapshot Comparison**   | Side-by-side comparison with difference highlighting       |
+| **Restore Functionality** | Preview and restore saved setpoint values                  |
+
+## Getting Started
+
+New to Squirrel? Start with the [Getting Started](getting-started.md) guide to learn the basics.
+
+## User Guide
+
+For detailed instructions on each feature, see the [User Guide](user-guide/index.md).

docs/stylesheets/extra.css

@@ -0,0 +1,13 @@
+/* Image styling for light mode */
+[data-md-color-scheme='default'] img {
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+/* Image styling for dark mode */
+[data-md-color-scheme='slate'] img {
+  border: 1px solid #404040;
+  border-radius: 4px;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
+}

docs/user-guide/index.md

@@ -0,0 +1,32 @@
+# User Guide
+
+This guide covers all the features of Squirrel in detail.
+
+## Core Workflows
+
+### Saving and Restoring Configurations
+
+1. **[Snapshots](snapshots.md)** - Create snapshots to save the current state of your PVs
+2. **[Restore](restore.md)** - Restore saved values back to the control system
+
+### Comparing Configurations
+
+3. **[Snapshot Comparison](snapshot-comparison.md)** - Compare two snapshots to see what changed
+
+### Managing PVs
+
+4. **[PV Browser](pv-browser.md)** - Find, add, and import PVs
+5. **[PV Details](pv-details.md)** - View detailed information about individual PVs
+6. **[Tags](tags.md)** - Organize PVs into groups for easier filtering
+
+## Quick Reference
+
+| Task                   | Where to Go                             |
+| ---------------------- | --------------------------------------- |
+| Save current PV values | Snapshots → Create Snapshot             |
+| View a saved snapshot  | Snapshots → Click snapshot name         |
+| Compare two snapshots  | Snapshot Details → Compare button       |
+| Find a specific PV     | PV Browser → Search                     |
+| Add new PVs            | PV Browser → Add PV or Import CSV       |
+| Restore saved values   | Snapshot Details → Select PVs → Restore |
+| Filter PVs by tag      | Any PV table → Tag filter dropdown      |

docs/user-guide/pv-browser.md

@@ -0,0 +1,91 @@
+# PV Browser
+
+The PV Browser lets you explore, search, and manage the Process Variables (PVs) in your system.
+
+## Accessing the PV Browser
+
+Click **PV Browser** in the sidebar to open the browser view.
+
+<!-- TODO: Add screenshot: images/pv-browser.png -->
+
+## Browsing PVs
+
+The PV Browser displays all configured PVs in a table:
+
+| Column          | Description                    |
+| --------------- | ------------------------------ |
+| **PV Name**     | The full process variable name |
+| **Device**      | The device this PV belongs to  |
+| **Description** | A human-readable description   |
+| **Live Value**  | Current real-time value        |
+| **Tags**        | Assigned tag groups            |
+
+## Searching for PVs
+
+Use the **search bar** to find specific PVs.
+
+### Wildcard Search
+
+You can use wildcards to search for patterns:
+
+- `*` matches any characters
+- `?` matches a single character
+
+**Examples:**
+
+| Search Pattern | Matches                       |
+| -------------- | ----------------------------- |
+| `QUAD:*`       | All PVs starting with "QUAD:" |
+| `*:BDES`       | All PVs ending with ":BDES"   |
+| `QUAD:*:BDES`  | BDES PVs for all QUADs        |
+
+## Adding PVs
+
+!!! warning "Admin Required"
+Adding PVs requires admin privileges.
+
+### Adding Individual PVs
+
+1. Click the **Add PV** button
+2. Enter the PV name
+3. Fill in optional details (device, description)
+4. Click **Add**
+
+### Importing from CSV
+
+For bulk additions, you can import PVs from a CSV file.
+
+1. Click the **Import CSV** button
+2. Select your CSV file
+3. Review the import preview
+4. Click **Import**
+
+<!-- TODO: Add screenshot: images/csv-import-dialog.png -->
+
+#### CSV Format
+
+The CSV file should have the following columns:
+
+```csv
+pv_name,device,description
+QUAD:001:BDES,QUAD:001,Quad 1 BDES setpoint
+QUAD:001:BACT,QUAD:001,Quad 1 BACT readback
+```
+
+!!! tip "CSV Headers"
+The first row should contain column headers. At minimum, `pv_name` is required.
+
+## Viewing PV Details
+
+Click on a PV name to open its [details page](pv-details.md).
+
+## Managing PV Tags
+
+You can assign tags to PVs to organize them into groups:
+
+1. Select one or more PVs using checkboxes
+2. Click the **Tags** button
+3. Select the tags to assign
+4. Click **Save**
+
+See [Tags](tags.md) for more information on tag management.