Add Documentation Page

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy MkDocs to Github Pages
+
+on:
+    release:
+        types:
+            - published
+    push:
+        branches:
+            - main
+permissions:
+    contents: write
+
+jobs:
+    docs:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repo
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: Set up UV
+              uses: astral-sh/setup-uv@v6
+
+            - name: Install Dependencies
+              run: |
+                  uv sync --extra dev --extra docs
+
+            - name: Set up 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)
+              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
+
+            - name: Build and upload docs (dev)
+              if: ${{ github.event_name == 'push' }}
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                  uv run mike deploy --update-aliases --allow-empty --push dev

docs/index.md

@@ -0,0 +1,80 @@
+# Spendwise Expense Tracker
+
+**Spendwise** is an open-source desktop application to track expenses by importing Bank of America PDF statements. It features intelligent merchant categorization, monthly spending statistics, and interactive heatmap visualizations to help you understand your spending patterns.
+
+## Features
+
+- **PDF Statement Import** - Import Bank of America PDF statements with automatic transaction extraction
+- **Smart Categorization** - Intelligent merchant recognition with fuzzy matching (90% accuracy threshold)
+- **Transaction Management** - Add, edit, delete, and search transactions with pagination
+- **Monthly Statistics** - View net income and top spending categories by month
+- **Spending Heatmap** - Interactive calendar showing daily spending intensity with color-coded visualization
+- **Auto-Recategorization** - Update a merchant's category once, and similar transactions are automatically recategorized
+
+## Installation
+
+Spendwise is installed as a Python package. It is strongly recommended to install the package via [uv](https://docs.astral.sh/uv/).
+
+Latest versions of Spendwise can be seen in the [Release](https://github.com/7174Andy/expense-tracker/releases) page.
+
+### Requirements
+
+- Python 3.11 or higher
+- macOS, Linux, or Windows
+
+### Quick Install
+
+First, install `uv` if you haven't already:
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then, install Spendwise Tracker:
+
+```bash
+uv tool install spendwise-tracker
+```
+
+Run the GUI after installation:
+
+```bash
+expense-tracker
+```
+
+## Quick Start
+
+### Importing Transactions
+
+1. Click the **Import Statement** button in the Transactions tab
+2. Select a Bank of America PDF statement
+3. Transactions are automatically parsed and categorized
+
+### Managing Transactions
+
+- **View**: Browse transactions with pagination (100 per page)
+- **Search**: Use the search bar to filter transactions by keyword
+- **Add**: Click "Add Expense" to manually enter a transaction
+- **Edit**: Double-click a transaction or select and click "Edit"
+- **Delete**: Select a transaction and click "Delete"
+
+### Viewing Statistics
+
+1. Navigate to the **Statistics** tab
+2. Use the `<` and `>` buttons to browse months with transaction data
+3. View monthly net income and top spending category
+
+### Analyzing Spending Patterns
+
+1. Navigate to the **Heatmap** tab
+2. View daily spending amounts on an interactive calendar
+3. Darker colors indicate higher spending
+4. Click on any day to filter transactions by that date
+
+## License
+
+Spendwise is released under MIT License.

docs/installation.md

@@ -0,0 +1,198 @@
+# Installation Guide
+
+This guide will walk you through installing, verifying, and uninstalling Spendwise Tracker.
+
+## Requirements
+
+Before installing Spendwise Tracker, ensure your system meets the following requirements:
+
+- **Python**: Version 3.11 or higher
+- **Operating System**: macOS, Linux, or Windows
+- **uv**: Package installer (installation instructions below)
+
+## Installing uv
+
+Spendwise Tracker is distributed as a Python package and is best installed using [uv](https://docs.astral.sh/uv/), a fast Python package installer and resolver.
+
+### macOS and Linux
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Windows
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After installation, you may need to restart your terminal or add uv to your PATH.
+
+## Installing Spendwise Tracker
+
+Once you have `uv` installed, you can install Spendwise Tracker using the `uv tool install` command:
+
+```bash
+uv tool install spendwise-tracker
+```
+
+This command will:
+
+1. Download the latest version of Spendwise Tracker from PyPI
+2. Install it in an isolated environment
+3. Make the `expense-tracker` command available in your terminal
+
+### Installing a Specific Version
+
+To install a specific version, use:
+
+```bash
+uv tool install spendwise-tracker==0.1.0
+```
+
+Check the [Releases](https://github.com/7174Andy/expense-tracker/releases) page for available versions.
+
+## Verifying the Installation
+
+After installation, verify that Spendwise Tracker is working correctly:
+
+### 1. Check the Command
+
+Verify that the `expense-tracker` command is available:
+
+```bash
+expense-tracker --version
+```
+
+This should display the installed version number.
+
+### 2. Launch the Application
+
+Start the application to ensure the GUI launches properly:
+
+```bash
+expense-tracker
+```
+
+The Spendwise Tracker GUI window should open. If the application starts successfully, the installation is complete!
+
+### 3. Verify Database Location
+
+On first launch, Spendwise Tracker will create its database files in a platform-specific location:
+
+- **macOS**: `~/Library/Application Support/spendwise-tracker/`
+- **Linux/Unix**: `~/.local/share/spendwise-tracker/`
+- **Windows**: `%LOCALAPPDATA%\spendwise-tracker\`
+
+You can verify these directories exist after launching the application once.
+
+## Troubleshooting
+
+### Command Not Found
+
+If you get a "command not found" error after installation:
+
+1. **Check if uv's bin directory is in your PATH**:
+
+   ```bash
+   echo $PATH  # macOS/Linux
+   echo %PATH% # Windows
+   ```
+
+2. **Add uv's bin directory to your PATH**:
+
+   - **macOS/Linux**: Add to `~/.bashrc` or `~/.zshrc`:
+     ```bash
+     export PATH="$HOME/.local/bin:$PATH"
+     ```
+   - **Windows**: uv typically adds itself to PATH automatically during installation
+
+3. **Restart your terminal** and try again
+
+### Python Version Issues
+
+If you encounter Python version errors:
+
+```bash
+# Check your Python version
+python --version
+```
+
+Or:
+
+```bash
+python3 --version
+```
+
+Ensure Python 3.11 or higher is installed. If not, install or update Python before proceeding.
+
+### Permission Errors
+
+On macOS/Linux, if you encounter permission errors, ensure you're not using `sudo`. The `uv tool install` command should work without elevated privileges.
+
+## Updating Spendwise Tracker
+
+To update to the latest version:
+
+```bash
+uv tool upgrade spendwise-tracker
+```
+
+To update to a specific version:
+
+```bash
+uv tool install spendwise-tracker==0.2.0 --force
+```
+
+## Uninstalling Spendwise Tracker
+
+### Uninstall the Application
+
+To remove Spendwise Tracker from your system:
+
+```bash
+uv tool uninstall spendwise-tracker
+```
+
+This will remove the application but **will not delete your data**.
+
+### Remove User Data
+
+If you also want to delete your transaction data and merchant categories, manually remove the data directory:
+
+#### macOS
+
+```bash
+rm -rf ~/Library/Application\ Support/spendwise-tracker/
+```
+
+#### Linux/Unix
+
+```bash
+rm -rf ~/.local/share/spendwise-tracker/
+```
+
+#### Windows
+
+```powershell
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\spendwise-tracker"
+```
+
+!!! warning "Data Loss Warning"
+Deleting the data directory will permanently remove all your transactions, merchant categories, and settings. This action cannot be undone. Make sure to back up your data if needed before proceeding.
+
+## Next Steps
+
+Now that you have Spendwise Tracker installed, check out:
+
+- [Quick Start Guide](quickstart.md) - Learn how to use the application
+- [User Guide](user-guide.md) - Detailed feature documentation
+- [FAQ](faq.md) - Common questions and answers
+
+## Getting Help
+
+If you encounter issues not covered in this guide:
+
+1. Check the [GitHub Issues](https://github.com/7174Andy/expense-tracker/issues) page
+2. Review the [FAQ](faq.md) documentation
+3. Open a new issue with details about your problem

mkdocs.yml

@@ -0,0 +1,22 @@
+site_name: Spendwise Documentation
+site_url: https://7174Andy.github.io/spendwise
+theme:
+  name: material
+  palette:
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: deep orange
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - scheme: default
+      primary: deep orange
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+nav:
+  - Home: index.md
+  - Installation: installation.md

pyproject.toml

@@ -17,8 +17,12 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=8.4.2",
-    "ruff>=0.14.4",
+    "pytest",
+    "ruff",
+]
+
+docs = [
+    "mkdocs-material",
 ]
 
 [project.scripts]