From 1f565f2ea6d7a5d667466f72f573c0ee2a7cf9bc Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Mon, 5 Jan 2026 18:45:50 -0800 Subject: [PATCH 01/12] init mkdocs --- docs/index.md | 17 +++++++++++++++++ mkdocs.yml | 4 ++++ pyproject.toml | 8 ++++++-- 3 files changed, 27 insertions(+), 2 deletions(-) create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..000ea34 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,17 @@ +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](https://www.mkdocs.org). + +## Commands + +* `mkdocs new [dir-name]` - Create a new project. +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs -h` - Print help message and exit. + +## Project layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..1319d13 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,4 @@ +site_name: My Docs +site_url: https://7174Andy.github.io/spendwise +theme: + name: material diff --git a/pyproject.toml b/pyproject.toml index 6f2a4db..1d06850 100644 --- a/pyproject.toml +++ b/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] From e815edc986fb15195d3ef5fa5fefdfa89d83597e Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Mon, 5 Jan 2026 18:45:59 -0800 Subject: [PATCH 02/12] add workflows for docs deployment --- .github/workflows/docs.yml | 46 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e965576 --- /dev/null +++ b/.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 From 981f9e333cb9ef4bb448aac136627af377054abe Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Tue, 6 Jan 2026 11:39:32 -0800 Subject: [PATCH 03/12] add dark/light mode --- mkdocs.yml | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 1319d13..7d1db91 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,22 @@ -site_name: My Docs +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 From a887273d37e5913ed54fb630555ea50b423d71f1 Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Tue, 6 Jan 2026 11:39:38 -0800 Subject: [PATCH 04/12] add index --- docs/index.md | 87 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 12 deletions(-) diff --git a/docs/index.md b/docs/index.md index 000ea34..639adbb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,80 @@ -# Welcome to MkDocs +# Spendwise Expense Tracker -For full documentation visit [mkdocs.org](https://www.mkdocs.org). +**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. -## Commands +## Features -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. +- **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 -## Project layout +## Installation - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. +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. From dfa92779e29e5b555fb70488fc455183a5b1389a Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Tue, 6 Jan 2026 11:39:43 -0800 Subject: [PATCH 05/12] add installation guide --- docs/installation.md | 198 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 docs/installation.md diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..40a62ee --- /dev/null +++ b/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 From 189661d02b451f3dc5e55ef22a41e0540036e344 Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:35:27 -0800 Subject: [PATCH 06/12] fix installation page --- docs/installation.md | 12 ++---------- mkdocs.yml | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 40a62ee..cba8ffa 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -179,20 +179,12 @@ 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 +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. ## 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 +2. Open a new issue with details about your problem diff --git a/mkdocs.yml b/mkdocs.yml index 7d1db91..9b0323c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,6 +17,49 @@ theme: icon: material/brightness-7 name: Switch to dark mode +markdown_extensions: + # Python Markdown extensions + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - tables + - toc: + permalink: true + toc_depth: 3 + + # PyMdown Extensions + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + nav: - Home: index.md - Installation: installation.md From 0ece2fe9aa6991c4428b80a10d5c6e1c375b4f4d Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:43:33 -0800 Subject: [PATCH 07/12] add page --- docs/categorization.md | 83 ++++++++++++++++++++++++++++++++++ docs/getting-started.md | 99 +++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 + 3 files changed, 184 insertions(+) create mode 100644 docs/categorization.md create mode 100644 docs/getting-started.md diff --git a/docs/categorization.md b/docs/categorization.md new file mode 100644 index 0000000..510f2fe --- /dev/null +++ b/docs/categorization.md @@ -0,0 +1,83 @@ +# Categorization + +Spendwise automatically categorizes transactions by recognizing merchant names. This page explains how the system works and how you can teach it new categories. + +## How It Works + +When a transaction is imported or added, Spendwise assigns a category through the following steps: + +```mermaid +flowchart TD + A[New transaction] --> B{Amount > 0?} + B -- Yes --> C[Assign 'Income'] + B -- No --> D[Normalize merchant name] + D --> E{Exact match in database?} + E -- Yes --> F[Use stored category] + E -- No --> G{Fuzzy match ≥ 90%?} + G -- Yes --> F + G -- No --> H[Assign 'Uncategorized'] +``` + +### Step 1: Income Detection + +If the transaction amount is positive, it is automatically categorized as **Income** regardless of the merchant name. + +### Step 2: Merchant Normalization + +For expenses, Spendwise normalizes the raw merchant description to create a consistent lookup key. Normalization includes: + +- Converting to uppercase +- Removing digits and special characters (`#`, `*`) +- Stripping common words like `PENDING`, `MOBILE`, `PURCHASE` +- Removing trailing state abbreviations (e.g., `CA`, `NY`) +- Collapsing extra whitespace + +For example: + +| Raw Description | Normalized Key | +|-------------------------------------|--------------------| +| `PENDING STARBUCKS #1234 CA` | `STARBUCKS` | +| `Mobile Purchase AMAZON.COM 56789` | `AMAZON.COM` | +| `TRADER JOE'S #567 LOS ANGELES CA` | `TRADER JOE'S LOS ANGELES` | + +### Step 3: Exact Match + +The normalized key is compared against stored merchant-category mappings in the database. If an exact match is found, that category is used. + +### Step 4: Fuzzy Match + +If no exact match exists, Spendwise uses fuzzy string matching (powered by [rapidfuzz](https://github.com/rapidfuzz/RapidFuzz)) to find the closest known merchant. A match is accepted only if the similarity score is **90% or higher**. + +This handles minor variations in how the same merchant appears across statements, such as: + +- `STARBUCKS` vs `STARBUCKS COFFEE` +- `AMAZON.COM` vs `AMAZON COM` + +If no match meets the 90% threshold, the transaction is labeled **Uncategorized**. + +## Teaching Spendwise New Categories + +You train the categorization system simply by editing transactions: + +1. **Double-click** a transaction (or select it and click **Edit Transaction**) +2. Change the **Category** field to your preferred category (e.g., `Groceries`, `Dining`, `Transport`) +3. Click **Save** + +When you save a category change, two things happen: + +1. **The merchant mapping is saved** -- Spendwise stores the normalized merchant name with its new category +2. **Uncategorized transactions are re-evaluated** -- All existing transactions marked as "Uncategorized" are checked against the updated mappings, and any that match (exact or fuzzy) are automatically recategorized + +!!! example + You edit a Starbucks transaction and change its category from "Uncategorized" to "Coffee". Spendwise saves the mapping `STARBUCKS → Coffee`. All other uncategorized Starbucks transactions are instantly recategorized to "Coffee" as well. + +## Category Suggestions + +When you open the edit dialog for an uncategorized transaction, Spendwise checks if a mapping already exists for that merchant's normalized name. If a match is found, the category field is pre-filled with the suggested category -- you can accept it by clicking **Save** or type a different one. + +## Tips for Effective Categorization + +- **Categorize early** -- The more merchant mappings Spendwise learns, the fewer uncategorized transactions you'll see on future imports. +- **Be consistent** -- Use the same category names across merchants (e.g., always use "Dining" rather than mixing "Dining", "Restaurants", and "Eating Out"). +- **Let fuzzy matching work for you** -- You don't need to categorize every slight variation of a merchant. Once you categorize `STARBUCKS`, variations like `STARBUCKS COFFEE` will match automatically. +- **Review after importing** -- After importing a new statement, scan for "Uncategorized" transactions and assign categories. Each one teaches Spendwise for future imports. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..10d5c37 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,99 @@ +# Getting Started + +This guide walks you through launching Spendwise for the first time, importing your first bank statement, and navigating the interface. + +## Launching the Application + +After [installing](installation.md) Spendwise, start it from your terminal: + +```bash +expense-tracker +``` + +The main window opens with three tabs: **Transactions**, **Statistics**, and **Heatmap**. + +## Importing a Bank Statement + +The fastest way to populate Spendwise is by importing a Bank of America PDF statement. + +### 1. Download Your Statement + +Log in to your Bank of America account and download a monthly statement as a PDF. + +!!! note + Only Bank of America PDF statements are supported at this time. Other bank formats will not be parsed correctly. + +### 2. Import the PDF + +1. In the **Transactions** tab, click **Import Statement** (top-right of the toolbar) +2. Click **Browse** and select your downloaded PDF +3. Click **Upload** + +Spendwise extracts each transaction from the PDF and automatically categorizes them using its [merchant categorization system](categorization.md). A success message confirms the import. + +### 3. Review Your Transactions + +After importing, your transactions appear in the table with the following columns: + +| Column | Description | +|-------------|--------------------------------------------------| +| Date | Transaction date | +| Amount | Negative for expenses, positive for income | +| Category | Auto-assigned category (or "Uncategorized") | +| Description | Original merchant description from the statement | + +## Adding a Transaction Manually + +You can also add transactions by hand: + +1. Click **Add Transaction** in the toolbar +2. Fill in the date, amount, category, and description +3. Click **Save** + +## Editing a Transaction + +To correct a transaction's details or update its category: + +1. **Double-click** a transaction in the table (or select it and click **Edit Transaction**) +2. Modify the amount, category, or description +3. Click **Save** + +!!! tip + When you change a transaction's category, Spendwise remembers the mapping and automatically applies it to other uncategorized transactions from the same merchant. See [Categorization](categorization.md) for details. + +## Deleting Transactions + +1. Select one or more transactions in the table +2. Click **Delete Transaction** +3. Confirm the deletion in the dialog + +## Searching Transactions + +Use the search bar in the toolbar to filter transactions by keyword: + +1. Type a keyword (e.g., a merchant name or category) into the search field +2. Press ++enter++ or click **Search** +3. Click **Clear Search** to remove the filter + +## Browsing Pages + +Transactions are displayed 100 per page, sorted by date (newest first). Use the **Previous** and **Next** buttons at the bottom to navigate between pages. + +## Viewing Statistics + +Switch to the **Statistics** tab to see monthly summaries: + +- **Net income** for the selected month +- **Top spending categories** ranked by total amount +- Use the **<** and **>** buttons to browse between months + +## Viewing the Spending Heatmap + +Switch to the **Heatmap** tab for a calendar visualization of your daily spending: + +- Darker colors indicate higher spending days +- Click on any day to jump to the **Transactions** tab filtered to that date + +## Next Steps + +- Learn how [Categorization](categorization.md) works to keep your transactions organized automatically diff --git a/mkdocs.yml b/mkdocs.yml index 9b0323c..16c1d18 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,3 +63,5 @@ markdown_extensions: nav: - Home: index.md - Installation: installation.md + - Getting Started: getting-started.md + - Categorization: categorization.md From 6f81e0552bf362c00c4356e08fb72575281b8025 Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:49:52 -0800 Subject: [PATCH 08/12] fix mistakes in the docs --- docs/getting-started.md | 2 +- docs/index.md | 6 +++--- docs/installation.md | 14 ++------------ 3 files changed, 6 insertions(+), 16 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 10d5c37..cc025e4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -47,7 +47,7 @@ After importing, your transactions appear in the table with the following column You can also add transactions by hand: 1. Click **Add Transaction** in the toolbar -2. Fill in the date, amount, category, and description +2. Fill in the amount, category, and description (the date defaults to today) 3. Click **Save** ## Editing a Transaction diff --git a/docs/index.md b/docs/index.md index 639adbb..5fc1119 100644 --- a/docs/index.md +++ b/docs/index.md @@ -58,9 +58,9 @@ expense-tracker - **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" +- **Add**: Click "Add Transaction" to manually enter a transaction +- **Edit**: Double-click a transaction or select and click "Edit Transaction" +- **Delete**: Select a transaction and click "Delete Transaction" ### Viewing Statistics diff --git a/docs/installation.md b/docs/installation.md index cba8ffa..a0070e0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -56,17 +56,7 @@ Check the [Releases](https://github.com/7174Andy/expense-tracker/releases) page 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 +### 1. Launch the Application Start the application to ensure the GUI launches properly: @@ -76,7 +66,7 @@ expense-tracker The Spendwise Tracker GUI window should open. If the application starts successfully, the installation is complete! -### 3. Verify Database Location +### 2. Verify Database Location On first launch, Spendwise Tracker will create its database files in a platform-specific location: From 8a34cfd7e53815610a691524e0b03ef797c12ce7 Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:49:57 -0800 Subject: [PATCH 09/12] add mike package --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 1d06850..7d7fa7d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,7 @@ dev = [ docs = [ "mkdocs-material", + "mike", ] [project.scripts] From fbe06316a6f5351d6e780cd1758a5c6aaa3c9ef0 Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:58:47 -0800 Subject: [PATCH 10/12] Add site/ to .gitignore The mkdocs build output directory should not be tracked. Co-Authored-By: Claude Opus 4.6 --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 2a50af5..60e4961 100644 --- a/.gitignore +++ b/.gitignore @@ -45,4 +45,7 @@ uv.lock .vscode/ # DS_Store files -.DS_Store \ No newline at end of file +.DS_Store + +# MkDocs build output +site/ From 5e696327ed81ee15937724cbdb45f5916ea4d20a Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:58:52 -0800 Subject: [PATCH 11/12] Redesign landing page with grid cards and icons Use Material theme components (grid cards, tabbed install blocks, admonition callouts, CTA buttons) for a more visually appealing home page. Co-Authored-By: Claude Opus 4.6 --- docs/index.md | 132 ++++++++++++++++++++++++++++++++------------------ mkdocs.yml | 2 + 2 files changed, 88 insertions(+), 46 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5fc1119..e8f4c7f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,80 +1,120 @@ # 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. +**Take control of your spending.** Spendwise is an open-source desktop app that imports your Bank of America PDF statements, automatically categorizes transactions, and visualizes your spending patterns -- all locally on your machine. + +[Get Started](getting-started.md){ .md-button .md-button--primary } +[Installation](installation.md){ .md-button } + +--- ## 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 +- :material-file-pdf-box:{ .lg .middle } **PDF Statement Import** -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. + Import Bank of America PDF statements and automatically extract every transaction -- no manual data entry needed. -### Requirements +- :material-tag-text:{ .lg .middle } **Smart Categorization** -- Python 3.11 or higher -- macOS, Linux, or Windows + --- -### Quick Install + Intelligent merchant recognition using fuzzy matching with a 90% accuracy threshold. Categorize once, and Spendwise remembers. -First, install `uv` if you haven't already: + [:octicons-arrow-right-24: How it works](categorization.md) -```bash -# macOS/Linux -curl -LsSf https://astral.sh/uv/install.sh | sh +- :material-table-edit:{ .lg .middle } **Transaction Management** -# Windows -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` + --- -Then, install Spendwise Tracker: + Add, edit, delete, and search transactions with a clean tabular interface and pagination. -```bash -uv tool install spendwise-tracker -``` +- :material-chart-bar:{ .lg .middle } **Monthly Statistics** + + --- + + View net income and top spending categories by month to understand where your money goes. + +- :material-calendar-month:{ .lg .middle } **Spending Heatmap** + + --- + + Interactive calendar visualization with color-coded daily spending. Click any day to drill into its transactions. + +- :material-sync:{ .lg .middle } **Auto-Recategorization** + + --- + + Update a merchant's category once, and all matching uncategorized transactions are instantly recategorized. + +
-Run the GUI after installation: +## Quick Install + +Install with [uv](https://docs.astral.sh/uv/) in two commands: + +=== "macOS / Linux" + + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + uv tool install spendwise-tracker + ``` + +=== "Windows" + + ```powershell + powershell -c "irm https://astral.sh/uv/install.ps1 | iex" + uv tool install spendwise-tracker + ``` + +Then launch the app: ```bash expense-tracker ``` +!!! tip "Need more details?" + See the full [Installation Guide](installation.md) for version pinning, troubleshooting, and uninstall instructions. + ## Quick Start -### Importing Transactions +
+ +- :material-numeric-1-circle:{ .lg .middle } **Import a statement** + + --- + + Click **Import Statement** in the toolbar, select a Bank of America PDF, and your transactions appear instantly. + +- :material-numeric-2-circle:{ .lg .middle } **Review & categorize** + + --- + + Double-click any transaction to edit its category. Spendwise learns and applies the mapping to future imports. + +- :material-numeric-3-circle:{ .lg .middle } **Search & browse** + + --- -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 + Use the search bar to filter by keyword. Navigate pages with **Previous** / **Next** (100 transactions per page). -### Managing Transactions +- :material-numeric-4-circle:{ .lg .middle } **Explore your data** -- **View**: Browse transactions with pagination (100 per page) -- **Search**: Use the search bar to filter transactions by keyword -- **Add**: Click "Add Transaction" to manually enter a transaction -- **Edit**: Double-click a transaction or select and click "Edit Transaction" -- **Delete**: Select a transaction and click "Delete Transaction" + --- -### Viewing Statistics + Switch to the **Statistics** tab for monthly summaries or the **Heatmap** tab for a calendar view of daily spending. -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 +## Requirements -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 +| | Requirement | +|---|---| +| :material-language-python: | Python 3.11 or higher | +| :material-desktop-classic: | macOS, Linux, or Windows | ## License -Spendwise is released under MIT License. +Spendwise is released under the [MIT License](https://github.com/7174Andy/expense-tracker/blob/main/LICENSE). diff --git a/mkdocs.yml b/mkdocs.yml index 16c1d18..9fbc037 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,8 @@ site_name: Spendwise Documentation site_url: https://7174Andy.github.io/spendwise theme: name: material + icon: + repo: fontawesome/brands/github palette: # Palette toggle for dark mode - scheme: slate From a998254a2e983192717e44266281fce5be8b693f Mon Sep 17 00:00:00 2001 From: 7174Andy Date: Fri, 13 Feb 2026 15:58:56 -0800 Subject: [PATCH 12/12] Add OS-specific tabs to installation guide Replace separate headings with tabbed content blocks so users can switch between macOS/Linux and Windows commands inline. Co-Authored-By: Claude Opus 4.6 --- docs/installation.md | 91 ++++++++++++++++++++++++++++---------------- 1 file changed, 59 insertions(+), 32 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index a0070e0..0f81271 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -14,17 +14,17 @@ Before installing Spendwise Tracker, ensure your system meets the following requ 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 +=== "macOS / Linux" -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -``` + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` -### Windows +=== "Windows" -```powershell -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` + ```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. @@ -70,9 +70,23 @@ The Spendwise Tracker GUI window should open. If the application starts successf 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\` +=== "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. @@ -84,18 +98,31 @@ 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 - ``` + === "macOS / Linux" + + ```bash + echo $PATH + ``` + + === "Windows" + + ```powershell + echo %PATH% + ``` 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 + === "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 @@ -150,23 +177,23 @@ This will remove the application but **will not delete your data**. If you also want to delete your transaction data and merchant categories, manually remove the data directory: -#### macOS +=== "macOS" -```bash -rm -rf ~/Library/Application\ Support/spendwise-tracker/ -``` + ```bash + rm -rf ~/Library/Application\ Support/spendwise-tracker/ + ``` -#### Linux/Unix +=== "Linux / Unix" -```bash -rm -rf ~/.local/share/spendwise-tracker/ -``` + ```bash + rm -rf ~/.local/share/spendwise-tracker/ + ``` -#### Windows +=== "Windows" -```powershell -Remove-Item -Recurse -Force "$env:LOCALAPPDATA\spendwise-tracker" -``` + ```powershell + Remove-Item -Recurse -Force "$env:LOCALAPPDATA\spendwise-tracker" + ``` !!! warning "Data Loss Warning"