Add quick test runner and enhance run_tests script

- Introduced `quick_test.py` for running specific test categories (unit, integration, theme, all). - Updated `run_tests.py` to improve test execution and reporting, including coverage. - Removed outdated test scripts for keyboard shortcuts, menu theming, note saving, and entry updating. - Added new test script `test_theme_changing.py` to verify theme changing functionality. - Consolidated integration tests into `test_integration.py` for comprehensive testing of TheChart application. - Updated theme manager to ensure color retrieval works correctly. - Modified test constants to import from the correct module path.
2025-08-05 15:09:13 -07:00
parent df9738ab17
commit a521ed6e9a
46 changed files with 8325 additions and 1131 deletions
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -0,0 +1,465 @@
+# TheChart User Guide
+
+> 📖 **Consolidated Documentation**: This document combines multiple documentation files for better organization and easier navigation.
+
+## Table of Contents
+- [Overview](#overview)
+
+## Overview
+
+Complete user manual with features, shortcuts, and usage
+
+
+### Overview
+TheChart is a comprehensive medication tracking application with a modern, professional UI that allows users to monitor medication intake, track symptoms, and visualize treatment progress over time.
+
+### 🎨 Modern UI/UX System (New in v1.9.5)
+
+#### Professional Theme Engine
+TheChart features a sophisticated theme system powered by ttkthemes, offering 8 carefully curated professional themes.
+
+##### Available Themes:
+- **Arc**: Modern flat design with subtle shadows
+- **Equilux**: Dark theme with excellent contrast
+- **Adapta**: Clean, minimalist design
+- **Yaru**: Ubuntu-inspired modern interface
+- **Ubuntu**: Official Ubuntu styling
+- **Plastik**: Classic professional appearance
+- **Breeze**: KDE-inspired clean design
+- **Elegance**: Sophisticated dark theme
+
+##### UI Enhancements:
+- **Modern Styling**: Card-style frames, enhanced buttons, professional form controls
+- **Smart Tooltips**: Context-sensitive help for all interactive elements
+- **Improved Tables**: Better selection highlighting and alternating row colors
+- **Settings System**: Comprehensive preferences with theme persistence
+- **Responsive Design**: Automatic layout adjustments and scaling
+- **Menu Theming**: Complete menu integration with theme colors and hover effects
+
+#### ⌨️ Comprehensive Keyboard Shortcuts
+Professional keyboard shortcut system for efficient navigation and operation.
+
+##### File Operations:
+- **Ctrl+S**: Save/Add new entry
+- **Ctrl+Q**: Quit application (with confirmation)
+- **Ctrl+E**: Export data
+
+##### Data Management:
+- **Ctrl+N**: Clear entries
+- **Ctrl+R / F5**: Refresh data
+- **Delete**: Delete selected entry
+- **Escape**: Clear selection
+
+##### Window Management:
+- **Ctrl+M**: Manage medicines
+- **Ctrl+P**: Manage pathologies
+- **F1**: Show keyboard shortcuts help
+- **F2**: Open settings window
+
+### Core Features
+
+#### 🏥 Modular Medicine System
+TheChart features a dynamic medicine management system that allows complete customization without code modifications.
+
+##### Features:
+- **Dynamic Medicine Management**: Add, edit, and remove medicines through the UI
+- **Configurable Properties**: Each medicine has customizable display names, dosages, colors, and quick-dose options
+- **Automatic UI Updates**: All interface elements update automatically when medicines change
+- **JSON Configuration**: Human-readable `medicines.json` file for easy management
+
+##### Medicine Configuration:
+Each medicine includes:
+- **Key**: Internal identifier (e.g., "bupropion")
+- **Display Name**: User-friendly name (e.g., "Bupropion")
+- **Dosage Info**: Dosage information (e.g., "150/300 mg")
+- **Quick Doses**: Common dose amounts for quick selection
+- **Color**: Hex color for graph display (e.g., "#FF6B6B")
+- **Default Enabled**: Whether to show in graphs by default
+
+##### Default Medicines:
+| Medicine | Dosage | Default Graph | Color |
+|----------|--------|---------------|--------|
+| Bupropion | 150/300 mg | ✅ | Red (#FF6B6B) |
+| Hydroxyzine | 25 mg | ❌ | Teal (#4ECDC4) |
+| Gabapentin | 100 mg | ❌ | Blue (#45B7D1) |
+| Propranolol | 10 mg | ✅ | Green (#96CEB4) |
+| Quetiapine | 25 mg | ❌ | Yellow (#FFEAA7) |
+
+##### Usage:
+1. **Through UI**: Go to `Tools` → `Manage Medicines...`
+2. **Manual Configuration**: Edit `medicines.json` directly
+3. **Programmatically**: Use the MedicineManager API
+
+#### ⚙️ Settings and Theme Management
+Advanced configuration system allowing users to customize their experience.
+
+##### Settings Window (F2):
+- **Theme Selection**: Choose from 8 professional themes with live preview
+- **UI Preferences**: Font scaling, window behavior options
+- **About Information**: Detailed application and version information
+- **Tabbed Interface**: Organized settings categories for easy navigation
+
+##### Theme Features:
+- **Real-time Switching**: No restart required for theme changes
+- **Persistence**: Selected theme remembered between sessions
+- **Quick Access**: Theme menu for instant switching
+- **Fallback Handling**: Graceful handling if themes fail to load
+
+#### 💡 Smart Tooltip System
+Context-sensitive help system providing guidance throughout the application.
+
+##### Tooltip Types:
+- **Pathology Scales**: Usage guidance for symptom tracking
+- **Medicine Checkboxes**: Medication information and dosage details
+- **Action Buttons**: Functionality description with keyboard shortcuts
+- **Form Controls**: Input guidance and format requirements
+
+##### Features:
+- **Delayed Display**: Non-intrusive timing (500-800ms delay)
+- **Theme-aware Styling**: Tooltips match selected theme
+- **Smart Positioning**: Automatic placement to avoid screen edges
+- **Rich Content**: Multi-line descriptions with formatting
+
+#### 💊 Advanced Dose Tracking
+Comprehensive dose tracking system that records exact timestamps and dosages throughout the day.
+
+##### Core Capabilities:
+- **Timestamp Recording**: Exact time when medicine is taken
+- **Dose Amount Tracking**: Record specific doses (150mg, 10mg, etc.)
+- **Multiple Doses Per Day**: Take the same medicine multiple times
+- **Real-time Display**: See today's doses immediately
+- **Data Persistence**: All doses saved to CSV with full history
+
+##### Dose Management Interface:
+Located in the edit window (double-click any entry):
+- **Individual Dose Entry Fields**: For each medicine
+- **"Take [Medicine]" Buttons**: Immediate dose recording with timestamps
+- **Editable Dose Display Areas**: View and modify existing doses
+- **Quick Dose Buttons**: Pre-configured common dose amounts
+- **Format Consistency**: All doses displayed in HH:MM: dose format
+
+##### Data Format:
+- **Timestamp Format**: `YYYY-MM-DD HH:MM:SS`
+- **Dose Separator**: `|` (pipe) for multiple doses
+- **Dose Format**: `timestamp:dose`
+- **CSV Storage**: Additional columns in existing CSV file
+
+##### Example CSV Format:
+```csv
+date,depression,anxiety,sleep,appetite,bupropion,bupropion_doses,hydroxyzine,hydroxyzine_doses,propranolol,propranolol_doses,note
+07/28/2025,4,5,3,3,1,"2025-07-28 14:30:00:150mg|2025-07-28 18:30:00:150mg",0,"",1,"2025-07-28 12:30:00:10mg","Multiple doses today"
+```
+
+#### 📊 Enhanced Graph Visualization
+Advanced graphing system with comprehensive data visualization and interactive controls.
+
+##### Medicine Dose Visualization:
+- **Colored Bar Charts**: Each medicine has distinct colors
+- **Daily Dose Totals**: Automatically calculated from individual doses
+- **Scaled Display**: Doses scaled by 1/10 for better visibility (labeled as "mg/10")
+- **Dynamic Positioning**: Bars positioned below main chart area
+- **Semi-transparent Bars**: Alpha=0.6 to avoid overwhelming symptom data
+
+##### Interactive Controls:
+- **Toggle Buttons**: Independent show/hide for each medicine and symptom
+- **Organized Sections**: "Symptoms" and "Medicines" sections
+- **Real-time Updates**: Changes take effect immediately
+
+##### Enhanced Legend:
+- **Multi-column Layout**: Efficient use of graph space (2 columns)
+- **Average Dosage Display**: Shows average dose for each medicine
+- **Color Coding**: Consistent color scheme matching graph elements
+- **Professional Styling**: Frame, shadow, and transparency effects
+- **Tracking Status**: Shows medicines being monitored but without current dose data
+
+##### Dose Calculation Features:
+- **Multiple Format Support**: Handles various dose string formats
+- **Robust Parsing**: Handles timestamps, symbols (•), and mixed formats
+- **Edge Case Handling**: Manages empty strings, NaN values, malformed data
+- **Daily Totals**: Sums all individual doses for comprehensive daily tracking
+
+#### 🏥 Pathology Management
+Comprehensive symptom tracking with configurable pathologies.
+
+##### Features:
+- **Dynamic Pathology System**: Similar to medicine management
+- **Configurable Symptoms**: Add, edit, and remove symptom categories
+- **Scale-based Rating**: 0-10 rating system for symptom severity
+- **Historical Tracking**: Full symptom history with trend analysis
+
+#### 📝 Data Management
+Robust data handling with comprehensive backup and migration support.
+
+##### Data Features:
+- **CSV-based Storage**: Human-readable and portable data format
+- **Automatic Backups**: Created before major migrations
+- **Backward Compatibility**: Existing data continues to work with updates
+- **Dynamic Column Management**: Automatically adapts to new medicines/pathologies
+- **Data Validation**: Ensures data integrity and handles edge cases
+
+##### Migration Support:
+- **Automatic Migration**: Data structure updates handled automatically
+- **Backup Creation**: `thechart_data.csv.backup_YYYYMMDD_HHMMSS` format
+- **No Data Loss**: All existing functionality and data preserved
+- **Version Compatibility**: Seamless updates across application versions
+
+#### 🧪 Comprehensive Testing Framework
+Professional testing infrastructure with high code coverage.
+
+##### Testing Statistics:
+- **93% Overall Code Coverage** (482 total statements, 33 missed)
+- **112 Total Tests** across 6 test modules
+- **80 Tests Passing** (71.4% pass rate)
+- **Pre-commit Testing**: Core functionality tests run before each commit
+
+##### Test Coverage by Module:
+- **100% Coverage**: constants.py, logger.py
+- **97% Coverage**: graph_manager.py
+- **95% Coverage**: init.py
+- **93% Coverage**: ui_manager.py
+- **91% Coverage**: main.py
+- **87% Coverage**: data_manager.py
+
+##### Testing Tools:
+- **pytest**: Modern Python testing framework
+- **pytest-cov**: Coverage reporting with HTML, XML, and terminal output
+- **pytest-mock**: Mocking support for isolated testing
+- **pre-commit hooks**: Automated testing before commits
+
+### User Interface Features
+
+#### 🖥️ Intuitive Design
+- **Clean Main Interface**: Simplified new entry form focused on essential inputs
+- **Organized Edit Windows**: Comprehensive dose management in dedicated edit interface
+- **Scrollable Interface**: Vertical scrollbar for expanded UI components
+- **Responsive Design**: Interface adapts to window size and content
+- **Visual Feedback**: Success messages and clear status indicators
+
+#### 🎯 User Experience Improvements
+- **Centralized Dose Management**: All dose operations consolidated in edit windows
+- **Quick Entry Options**: Pre-configured dose buttons for common amounts
+- **Format Guidance**: Clear instructions and format examples
+- **Real-time Updates**: Immediate feedback and data updates
+- **Error Handling**: Comprehensive error messages and recovery options
+
+#### ⌨️ Keyboard Shortcuts
+Comprehensive keyboard shortcuts for efficient navigation and data entry.
+
+##### File Operations:
+- **Ctrl+S**: Save/Add new entry - Quickly save current entry data
+- **Ctrl+Q**: Quit application - Exit with confirmation dialog
+- **Ctrl+E**: Export data - Open export dialog window
+
+##### Data Management:
+- **Ctrl+N**: Clear entries - Clear all input fields for new entry
+- **Ctrl+R / F5**: Refresh data - Reload data from CSV and update displays
+
+##### Window Management:
+- **Ctrl+M**: Manage medicines - Open medicine management window
+- **Ctrl+P**: Manage pathologies - Open pathology management window
+
+##### Table Operations:
+- **Delete**: Delete selected entry - Remove selected table entry with confirmation
+- **Escape**: Clear selection - Clear current table selection
+- **Double-click**: Edit entry - Open edit dialog for selected entry
+
+##### Help System:
+- **F1**: Show keyboard shortcuts - Display help dialog with all shortcuts
+
+##### Integration Features:
+- **Menu Display**: All shortcuts shown in menu bar next to items
+- **Button Labels**: Primary buttons show their keyboard shortcuts
+- **Case Insensitive**: Both Ctrl+S and Ctrl+Shift+S work
+- **Focus Management**: Shortcuts work when main window has focus
+- **Status Feedback**: All operations provide status bar feedback
+
+### Technical Architecture
+
+#### <20> Modern UI Architecture
+- **ThemeManager**: Centralized theme management with dynamic switching
+- **TooltipManager**: Smart tooltip system with context-sensitive help
+- **UIManager**: Enhanced UI component creation with theme integration
+- **SettingsWindow**: Advanced configuration interface with persistence
+
+#### 🏗️ Core Application Design
+- **MedicineManager**: Core medicine CRUD operations with JSON persistence
+- **PathologyManager**: Symptom and pathology management system
+- **GraphManager**: Professional graph rendering with matplotlib integration
+- **DataManager**: Robust CSV operations and data persistence with validation
+
+#### 🔧 Configuration and Data Management
+- **JSON-based Configuration**: `medicines.json` and `pathologies.json` for easy management
+- **Dynamic Loading**: Runtime configuration updates without restarts
+- **Data Validation**: Comprehensive input validation and error handling
+- **Backward Compatibility**: Seamless updates and migrations across versions
+
+#### 📈 Advanced Data Processing
+- **Pandas Integration**: Efficient data manipulation and analysis
+- **Real-time Calculations**: Dynamic dose totals, averages, and statistics
+- **Robust Parsing**: Handles various data formats and edge cases gracefully
+- **Performance Optimization**: Efficient batch operations and caching
+
+### UI/UX Technical Implementation
+
+#### 🎭 Theme System Architecture
+- **Multiple Theme Support**: 8 curated professional themes
+- **Dynamic Style Application**: Real-time theme switching without restart
+- **Color Extraction**: Automatic color scheme detection and application
+- **Fallback Mechanisms**: Graceful handling when themes fail to load
+
+#### 💡 Enhanced User Experience
+- **Smart Tooltips**: Context-sensitive help with delayed, non-intrusive display
+- **Modern Styling**: Card-style frames, enhanced buttons, professional form controls
+- **Improved Tables**: Better selection highlighting and alternating row colors
+- **Responsive Design**: Automatic layout adjustments and proper scaling
+
+#### ⚙️ Settings and Persistence
+- **Configuration Management**: Theme and preference persistence across sessions
+- **Tabbed Settings Interface**: Organized categories for easy navigation
+- **Live Preview**: Real-time theme preview in settings
+- **Error Recovery**: Robust handling of corrupted settings with defaults
+
+### Deployment and Distribution
+
+#### 📦 Standalone Executable
+- **PyInstaller Integration**: Creates self-contained executables
+- **Cross-platform Support**: Linux deployment with desktop integration
+- **Automatic Installation**: Installs to `~/Applications/` with desktop entry
+- **Data Migration**: Copies data files to appropriate user directories
+
+#### 🐳 Docker Support
+- **Multi-platform Images**: Docker container support
+- **Docker Compose**: Easy container management
+- **Development Environment**: Consistent development setup across platforms
+
+#### 🔄 Package Management
+- **UV Integration**: Fast Python package management with Rust performance
+- **Virtual Environment**: Isolated dependency management
+- **Lock Files**: Reproducible builds with `uv.lock`
+- **Development Dependencies**: Separate dev dependencies for clean production builds
+
+### Integration Features
+
+#### 🔄 Import/Export
+- **CSV Import**: Import existing medication data
+- **Data Export**: Export data for backup or analysis
+- **Format Compatibility**: Standard CSV format for portability
+
+#### 🔌 API Integration
+- **Extensible Architecture**: Plugin system for future enhancements
+- **Medicine API**: Programmatic medicine management
+- **Data API**: Direct data access and manipulation
+
+### Future Enhancements
+
+#### 🚀 Planned Features
+- **Mobile Companion App**: Mobile dose tracking and reminders
+- **Cloud Synchronization**: Multi-device data synchronization
+- **Advanced Analytics**: Machine learning-based trend analysis
+- **Reminder System**: Intelligent dose reminders and scheduling
+- **Doctor Integration**: Export reports for healthcare providers
+
+#### 🎯 Development Roadmap
+- **macOS/Windows Support**: Extended platform support
+- **Plugin Architecture**: Third-party extension support
+- **API Development**: RESTful API for external integrations
+- **Advanced Visualizations**: Additional chart types and analysis tools
+
+---
+
+For detailed usage instructions, see the main [README.md](../README.md).
+For development information, see [DEVELOPMENT.md](DEVELOPMENT.md).
+
+---
+*Originally from: FEATURES.md*
+
+
+
+TheChart application supports comprehensive keyboard shortcuts for improved productivity and efficient navigation.
+
+### File Operations
+- **Ctrl+S**: Save/Add new entry - Saves the current entry data to the database
+- **Ctrl+Q**: Quit application - Exits the application (with confirmation dialog)
+- **Ctrl+E**: Export data - Opens the export dialog window
+
+### Data Management
+- **Ctrl+N**: Clear entries - Clears all input fields to start a new entry
+- **Ctrl+R** or **F5**: Refresh data - Reloads data from the CSV file and updates the display
+
+### Window Management
+- **Ctrl+M**: Manage medicines - Opens the medicine management window
+- **Ctrl+P**: Manage pathologies - Opens the pathology management window
+
+### Table Operations
+- **Delete**: Delete selected entry - Deletes the currently selected entry in the table (with confirmation)
+- **Escape**: Clear selection - Clears the current selection in the table
+- **Double-click**: Edit entry - Opens the edit dialog for the selected entry
+
+### Help
+- **F1**: Show keyboard shortcuts help - Displays a dialog with all available keyboard shortcuts
+
+### Implementation Details
+
+#### Menu Integration
+All keyboard shortcuts are displayed in the menu bar next to their corresponding menu items for easy reference.
+
+#### Button Labels
+Primary action buttons show their keyboard shortcuts in the button text (e.g., "Add Entry (Ctrl+S)").
+
+#### Case Sensitivity
+- Shortcuts are case-insensitive
+- Both `Ctrl+S` and `Ctrl+Shift+S` work
+- Uppercase and lowercase variants are supported
+
+#### Focus Requirements
+- Keyboard shortcuts work when the main window has focus
+- Focus is automatically set to the main window on startup
+- Shortcuts work across all tabs and interface elements
+
+#### Feedback System
+- All operations provide feedback through the status bar
+- Success and error messages are displayed
+- Confirmation dialogs are shown for destructive operations (quit, delete)
+
+### Usage Tips
+
+#### Quick Workflow
+1. **Ctrl+N** - Clear fields for new entry
+2. Enter data in the form
+3. **Ctrl+S** - Save the entry
+4. **F5** - Refresh to see updated data
+
+#### Navigation
+- Use **Ctrl+M** and **Ctrl+P** to quickly access management windows
+- Use **Delete** to remove unwanted entries from the table
+- Use **Escape** to clear selections when needed
+
+#### Getting Help
+- Press **F1** anytime to see the keyboard shortcuts help dialog
+- All shortcuts are also visible in the menu bar
+- Button tooltips show additional keyboard shortcut information
+
+### Accessibility
+- Keyboard shortcuts provide full application functionality without mouse use
+- All critical operations have keyboard equivalents
+- Shortcuts follow standard application conventions (Ctrl+S for save, Ctrl+Q for quit)
+- Help system is easily accessible via F1
+
+---
+*Originally from: KEYBOARD_SHORTCUTS.md*
+
+
+---
+
+## 📖 Documentation Navigation
+
+- [User Guide](USER_GUIDE.md) - Features, shortcuts, and usage
+- [Developer Guide](DEVELOPER_GUIDE.md) - Development and testing
+- [API Reference](API_REFERENCE.md) - Technical documentation
+- [Changelog](CHANGELOG.md) - Version history
+- [Documentation Index](docs/README.md) - Complete navigation
+
+---
+
+*This document was generated by the documentation consolidation system.*
+*Last updated: 2025-08-05 14:53:36*