feat: Consolidate documentation into a single comprehensive guide
- Created `CONSOLIDATED_DOCS.md` to serve as the primary documentation source, integrating user and developer guides, API references, and troubleshooting sections. - Updated `README.md` to reference the new consolidated documentation. - Preserved existing documentation files for backward compatibility, including `USER_GUIDE.md`, `DEVELOPER_GUIDE.md`, and others. - Enhanced navigation structure in `docs/README.md` to facilitate easier access to documentation. - Implemented UI flickering fixes, including auto-save optimizations, debounced filter updates, and efficient tree updates to improve user experience. - Added verification script `verify_docs_consolidation.py` to ensure successful documentation consolidation and integrity.
This commit is contained in:
William Valentin
504
CONSOLIDATED_DOCS.md
Normal file
504
CONSOLIDATED_DOCS.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# TheChart - Comprehensive Documentation
|
||||
|
||||
> **Modern medication tracking application with advanced UI/UX for monitoring treatment progress and symptom evolution.**
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
1. [Quick Start](#-quick-start)
|
||||
2. [User Guide](#-user-guide)
|
||||
3. [Developer Guide](#-developer-guide)
|
||||
4. [Features & Capabilities](#-features--capabilities)
|
||||
5. [Technical Architecture](#-technical-architecture)
|
||||
6. [Recent Improvements](#-recent-improvements)
|
||||
7. [API Reference](#-api-reference)
|
||||
8. [Troubleshooting](#-troubleshooting)
|
||||
9. [Contributing](#-contributing)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Installation
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd thechart
|
||||
|
||||
# Install dependencies
|
||||
make install
|
||||
|
||||
# Run the application
|
||||
make run
|
||||
```
|
||||
|
||||
### First Steps
|
||||
1. **Launch TheChart** using `make run` or `python src/main.py`
|
||||
2. **Add your first entry** using Ctrl+S
|
||||
3. **Explore features** with the keyboard shortcuts (F1 for help)
|
||||
4. **Customize settings** with F2 or through the Theme menu
|
||||
|
||||
---
|
||||
|
||||
## 👤 User Guide
|
||||
|
||||
### Core Features
|
||||
|
||||
#### 📊 Data Tracking
|
||||
- **Daily Entries**: Track medications and symptoms with date-based entries
|
||||
- **Medicine Management**: Configure medications with dosage information and colors
|
||||
- **Pathology Tracking**: Monitor symptoms using customizable 0-10 scales
|
||||
- **Notes System**: Add detailed notes to each entry
|
||||
|
||||
#### 🎨 Modern UI/UX (v1.9.5+)
|
||||
- **Professional Themes**: Multiple built-in themes (Dark, Light, Arc, etc.)
|
||||
- **Smart Tooltips**: Context-sensitive help throughout the interface
|
||||
- **Responsive Design**: Optimized layouts for different screen sizes
|
||||
- **Smooth Interactions**: Debounced updates and flicker-free scrolling
|
||||
|
||||
#### ⌨️ Keyboard Shortcuts
|
||||
|
||||
##### File Operations
|
||||
- **Ctrl+S**: Save/Add new entry
|
||||
- **Ctrl+Q**: Quit application
|
||||
- **Ctrl+E**: Export data
|
||||
|
||||
##### Data Management
|
||||
- **Ctrl+N**: Clear entries
|
||||
- **Ctrl+R / F5**: Refresh data
|
||||
- **Ctrl+F**: Toggle search/filter
|
||||
|
||||
##### Window Management
|
||||
- **Ctrl+M**: Manage medicines
|
||||
- **Ctrl+P**: Manage pathologies
|
||||
|
||||
##### Table Operations
|
||||
- **Delete**: Delete selected entry
|
||||
- **Escape**: Clear selection
|
||||
- **Double-click**: Edit entry
|
||||
|
||||
##### Help
|
||||
- **F1**: Show keyboard shortcuts
|
||||
- **F2**: Open settings window
|
||||
|
||||
#### 🔍 Search & Filter System
|
||||
- **Text Search**: Search across all entry data
|
||||
- **Date Range Filtering**: Filter by specific date ranges
|
||||
- **Medicine Filters**: Show entries where medicines were taken/not taken
|
||||
- **Pathology Range Filters**: Filter by symptom severity ranges
|
||||
- **Quick Filters**: Pre-configured filters (last week, high symptoms, etc.)
|
||||
|
||||
#### 📈 Visualization
|
||||
- **Interactive Graphs**: Line charts showing symptom trends over time
|
||||
- **Medicine Dose Charts**: Bar charts displaying daily medication intake
|
||||
- **Toggle Controls**: Show/hide specific symptoms or medicines
|
||||
- **Professional Styling**: Clean, medical-grade visualization
|
||||
|
||||
#### 💾 Data Management
|
||||
- **Auto-save**: Automatic data saving every 5 minutes
|
||||
- **Backup System**: Automatic backups on startup/shutdown
|
||||
- **Export Options**: JSON, PDF, XML export formats
|
||||
- **Data Validation**: Comprehensive input validation and error handling
|
||||
|
||||
### Settings & Customization
|
||||
|
||||
#### Theme Management
|
||||
- **Built-in Themes**: Dark, Light, Arc, Clam, Default, Alt
|
||||
- **Dynamic Switching**: Change themes without restart
|
||||
- **Persistent Settings**: Theme preferences saved automatically
|
||||
- **Accessibility**: High contrast options available
|
||||
|
||||
#### Medicine Configuration
|
||||
- **Add/Edit/Delete**: Full CRUD operations for medicines
|
||||
- **Dosage Information**: Track dosage details and instructions
|
||||
- **Color Coding**: Visual identification with custom colors
|
||||
- **Quick Doses**: Pre-configured common dose amounts
|
||||
|
||||
#### Pathology Configuration
|
||||
- **Symptom Scales**: Customizable 0-10 symptom tracking scales
|
||||
- **Display Names**: User-friendly symptom names
|
||||
- **Scale Descriptions**: Helpful descriptions for each scale level
|
||||
- **Color Themes**: Visual feedback with color coding
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Developer Guide
|
||||
|
||||
### Development Environment Setup
|
||||
|
||||
#### Prerequisites
|
||||
- **Python 3.13+**
|
||||
- **uv** package manager
|
||||
- **Virtual environment support**
|
||||
|
||||
#### Setup Commands
|
||||
```bash
|
||||
# Create virtual environment
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # or .venv/bin/activate.fish
|
||||
|
||||
# Install dependencies
|
||||
uv sync
|
||||
|
||||
# Install development dependencies
|
||||
uv sync --group dev
|
||||
|
||||
# Run tests
|
||||
uv run pytest
|
||||
|
||||
# Run with coverage
|
||||
uv run pytest --cov=src --cov-report=html
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
thechart/
|
||||
├── src/ # Source code
|
||||
│ ├── main.py # Application entry point
|
||||
│ ├── ui_manager.py # UI component management
|
||||
│ ├── data_manager.py # Data persistence
|
||||
│ ├── theme_manager.py # Theme and styling
|
||||
│ ├── medicine_manager.py # Medicine CRUD operations
|
||||
│ ├── pathology_manager.py # Pathology management
|
||||
│ ├── graph_manager.py # Visualization
|
||||
│ ├── export_manager.py # Data export
|
||||
│ ├── search_filter*.py # Search and filtering
|
||||
│ └── auto_save.py # Auto-save functionality
|
||||
├── tests/ # Test suite
|
||||
├── docs/ # Documentation
|
||||
├── scripts/ # Utility scripts
|
||||
└── logs/ # Application logs
|
||||
```
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
#### Core Components
|
||||
- **MedTrackerApp**: Main application class coordinating all components
|
||||
- **UIManager**: Creates and manages all UI elements
|
||||
- **DataManager**: Handles CSV data operations with pandas
|
||||
- **ThemeManager**: Manages application themes and styling
|
||||
- **GraphManager**: Creates interactive matplotlib visualizations
|
||||
|
||||
#### Design Patterns
|
||||
- **Manager Pattern**: Separate managers for different concerns
|
||||
- **Observer Pattern**: UI updates based on data changes
|
||||
- **Strategy Pattern**: Different export formats and themes
|
||||
- **Factory Pattern**: Dynamic UI component creation
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
#### Test Organization
|
||||
- **Unit Tests**: Individual component testing
|
||||
- **Integration Tests**: Cross-component functionality
|
||||
- **UI Tests**: User interface behavior testing
|
||||
- **Performance Tests**: Load and stress testing
|
||||
|
||||
#### Running Tests
|
||||
```bash
|
||||
# All tests
|
||||
make test
|
||||
|
||||
# Specific test categories
|
||||
uv run pytest tests/unit/
|
||||
uv run pytest tests/integration/
|
||||
uv run pytest tests/ui/
|
||||
|
||||
# With coverage
|
||||
uv run pytest --cov=src --cov-report=html --cov-report=term-missing
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
#### Linting and Formatting
|
||||
- **ruff**: Primary linter and formatter
|
||||
- **Type Hints**: Full type annotation coverage
|
||||
- **PEP8 Compliance**: Enforced code style
|
||||
- **Docstrings**: Comprehensive documentation
|
||||
|
||||
#### Pre-commit Hooks
|
||||
```bash
|
||||
# Install pre-commit hooks
|
||||
pre-commit install
|
||||
|
||||
# Run all hooks
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Features & Capabilities
|
||||
|
||||
### Data Management Features
|
||||
- **Dynamic Medicine System**: Add/remove medicines without code changes
|
||||
- **Flexible Pathology Tracking**: Customizable symptom scales
|
||||
- **Robust Data Validation**: Comprehensive input validation
|
||||
- **Data Export**: Multiple export formats (JSON, PDF, XML)
|
||||
- **Backup & Recovery**: Automatic backup system
|
||||
|
||||
### User Interface Features
|
||||
- **Modern Theme Engine**: Professional styling system
|
||||
- **Smart Tooltip System**: Context-sensitive help
|
||||
- **Responsive Layouts**: Adaptive UI components
|
||||
- **Keyboard Navigation**: Full keyboard accessibility
|
||||
- **Visual Feedback**: Status updates and progress indicators
|
||||
|
||||
### Technical Features
|
||||
- **Performance Optimization**: Efficient data handling and UI updates
|
||||
- **Error Handling**: Comprehensive error recovery
|
||||
- **Logging System**: Detailed application logging
|
||||
- **Cross-platform**: Works on Windows, macOS, and Linux
|
||||
- **Modular Architecture**: Easy to extend and maintain
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Technical Architecture
|
||||
|
||||
### Data Layer
|
||||
- **CSV Storage**: Primary data persistence using pandas
|
||||
- **JSON Configuration**: Medicine and pathology configurations
|
||||
- **Backup System**: Automatic backup creation and management
|
||||
- **Data Validation**: Input validation and error handling
|
||||
|
||||
### Business Logic Layer
|
||||
- **Manager Classes**: Encapsulated business logic
|
||||
- **Event Handling**: User interaction processing
|
||||
- **Auto-save**: Background data persistence
|
||||
- **Export Processing**: Data transformation for export
|
||||
|
||||
### Presentation Layer
|
||||
- **Tkinter UI**: Native desktop interface
|
||||
- **Theme System**: Dynamic styling and theming
|
||||
- **Interactive Components**: Responsive UI elements
|
||||
- **Visualization**: Matplotlib integration for charts
|
||||
|
||||
### Recent Technical Improvements
|
||||
|
||||
#### UI Flickering Fix (Latest)
|
||||
- **Auto-save Optimization**: Removed unnecessary UI refreshes during auto-save
|
||||
- **Debounced Filter Updates**: 300ms debouncing for search/filter changes
|
||||
- **Efficient Tree Updates**: Scroll position preservation and batch operations
|
||||
- **Optimized Scroll Handling**: Reduced scrollbar update frequency
|
||||
- **Performance Improvements**: Eliminated redundant data loading
|
||||
|
||||
#### Key Optimizations
|
||||
1. **Memory Efficiency**: Single data load with copies instead of multiple loads
|
||||
2. **Scroll Performance**: Threshold-based scroll updates to reduce CPU usage
|
||||
3. **UI Responsiveness**: Batch UI operations using `update_idletasks()`
|
||||
4. **User Experience**: Preserved scroll position during data updates
|
||||
|
||||
---
|
||||
|
||||
## 📈 Recent Improvements
|
||||
|
||||
### Version 1.9.5 - UI/UX Overhaul
|
||||
- **Professional Theme Engine**: Complete theming system with 6+ themes
|
||||
- **Smart Tooltip System**: Context-sensitive help throughout the interface
|
||||
- **Enhanced Settings Window**: Comprehensive configuration interface
|
||||
- **Modern UI Components**: Improved styling and layout
|
||||
- **Performance Optimizations**: Faster loading and smoother interactions
|
||||
|
||||
### Latest Fixes - UI Flickering Resolution
|
||||
- **Smooth Scrolling**: Eliminated flickering during table scrolling
|
||||
- **Debounced Updates**: Reduced filter update frequency
|
||||
- **Preserved Context**: Maintain scroll position during updates
|
||||
- **Auto-save Optimization**: Non-intrusive background saving
|
||||
- **Performance Gains**: Reduced CPU usage during UI operations
|
||||
|
||||
### Previous Improvements
|
||||
- **Search & Filter System**: Advanced filtering capabilities
|
||||
- **Export Enhancements**: Multiple export formats with customization
|
||||
- **Keyboard Shortcuts**: Comprehensive keyboard navigation
|
||||
- **Data Validation**: Robust input validation and error handling
|
||||
- **Auto-save & Backup**: Automatic data protection
|
||||
|
||||
---
|
||||
|
||||
## 📖 API Reference
|
||||
|
||||
### Core Classes
|
||||
|
||||
#### MedTrackerApp
|
||||
```python
|
||||
class MedTrackerApp:
|
||||
"""Main application class."""
|
||||
|
||||
def __init__(self, root: tk.Tk) -> None:
|
||||
"""Initialize the application."""
|
||||
|
||||
def add_new_entry(self) -> None:
|
||||
"""Add a new data entry."""
|
||||
|
||||
def refresh_data_display(self, apply_filters: bool = False) -> None:
|
||||
"""Refresh the data display."""
|
||||
```
|
||||
|
||||
#### UIManager
|
||||
```python
|
||||
class UIManager:
|
||||
"""Manages UI components and creation."""
|
||||
|
||||
def create_input_frame(self, parent_frame: ttk.Frame) -> dict[str, Any]:
|
||||
"""Create the input form."""
|
||||
|
||||
def create_table_frame(self, parent_frame: ttk.Frame) -> dict[str, Any]:
|
||||
"""Create the data table."""
|
||||
|
||||
def update_status(self, message: str, message_type: str = "info") -> None:
|
||||
"""Update the status bar."""
|
||||
```
|
||||
|
||||
#### DataManager
|
||||
```python
|
||||
class DataManager:
|
||||
"""Handles data persistence and operations."""
|
||||
|
||||
def load_data(self) -> pd.DataFrame:
|
||||
"""Load data from CSV file."""
|
||||
|
||||
def add_entry(self, entry: list) -> bool:
|
||||
"""Add a new entry to the data."""
|
||||
|
||||
def update_entry(self, date: str, values: list) -> bool:
|
||||
"""Update an existing entry."""
|
||||
```
|
||||
|
||||
### Configuration APIs
|
||||
|
||||
#### Medicine Management
|
||||
```python
|
||||
class MedicineManager:
|
||||
"""Manages medicine configurations."""
|
||||
|
||||
def add_medicine(self, medicine: Medicine) -> bool:
|
||||
"""Add a new medicine."""
|
||||
|
||||
def get_medicine(self, key: str) -> Medicine | None:
|
||||
"""Get medicine by key."""
|
||||
|
||||
def get_medicine_keys(self) -> list[str]:
|
||||
"""Get all medicine keys."""
|
||||
```
|
||||
|
||||
#### Pathology Management
|
||||
```python
|
||||
class PathologyManager:
|
||||
"""Manages pathology configurations."""
|
||||
|
||||
def add_pathology(self, pathology: Pathology) -> bool:
|
||||
"""Add a new pathology."""
|
||||
|
||||
def get_pathology(self, key: str) -> Pathology | None:
|
||||
"""Get pathology by key."""
|
||||
|
||||
def get_pathology_keys(self) -> list[str]:
|
||||
"""Get all pathology keys."""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Application Won't Start
|
||||
```bash
|
||||
# Check Python version
|
||||
python --version # Should be 3.13+
|
||||
|
||||
# Verify virtual environment
|
||||
source .venv/bin/activate
|
||||
which python
|
||||
|
||||
# Reinstall dependencies
|
||||
uv sync --reinstall
|
||||
```
|
||||
|
||||
#### UI Flickering (Resolved)
|
||||
The UI flickering issue during scrolling has been resolved in the latest version through:
|
||||
- Auto-save optimization
|
||||
- Debounced filter updates
|
||||
- Efficient tree updates
|
||||
- Scroll position preservation
|
||||
|
||||
#### Data Not Saving
|
||||
1. Check file permissions in the project directory
|
||||
2. Verify CSV file is not locked by another application
|
||||
3. Check logs in `logs/app.log` for error messages
|
||||
4. Ensure sufficient disk space
|
||||
|
||||
#### Theme Issues
|
||||
1. Restart the application after theme changes
|
||||
2. Check theme configuration in settings
|
||||
3. Reset to default theme if issues persist
|
||||
4. Verify tkinter supports the selected theme
|
||||
|
||||
#### Export Problems
|
||||
1. Check output directory permissions
|
||||
2. Verify required libraries are installed
|
||||
3. Check for large dataset memory issues
|
||||
4. Review export logs for specific errors
|
||||
|
||||
### Debug Mode
|
||||
Enable debug logging by setting the log level in `src/constants.py`:
|
||||
```python
|
||||
LOG_LEVEL = "DEBUG"
|
||||
```
|
||||
|
||||
### Log Files
|
||||
- **`logs/app.log`**: General application logs
|
||||
- **`logs/app.error.log`**: Error messages only
|
||||
- **`logs/app.warning.log`**: Warning messages only
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
### Development Workflow
|
||||
1. **Fork** the repository
|
||||
2. **Create** a feature branch: `git checkout -b feature-name`
|
||||
3. **Make** your changes following the coding guidelines
|
||||
4. **Test** your changes: `make test`
|
||||
5. **Lint** your code: `ruff check src/`
|
||||
6. **Submit** a pull request
|
||||
|
||||
### Coding Standards
|
||||
- **Follow PEP8** for Python code style
|
||||
- **Use type hints** for all functions and variables
|
||||
- **Write docstrings** for all public methods and classes
|
||||
- **Add tests** for new functionality
|
||||
- **Update documentation** for user-facing changes
|
||||
|
||||
### Testing Requirements
|
||||
- **Unit tests** for all new functions
|
||||
- **Integration tests** for cross-component features
|
||||
- **UI tests** for user interface changes
|
||||
- **Performance tests** for optimization changes
|
||||
|
||||
### Documentation Updates
|
||||
- **Update user guide** for new features
|
||||
- **Add API documentation** for new classes/methods
|
||||
- **Update changelog** with version information
|
||||
- **Include troubleshooting** for known issues
|
||||
|
||||
---
|
||||
|
||||
## 📄 License & Credits
|
||||
|
||||
### License
|
||||
This project is licensed under [LICENSE] - see the LICENSE file for details.
|
||||
|
||||
### Credits
|
||||
- **UI Framework**: Tkinter (Python standard library)
|
||||
- **Data Processing**: pandas
|
||||
- **Visualization**: matplotlib
|
||||
- **Themes**: ttkthemes integration
|
||||
- **Package Management**: uv
|
||||
|
||||
### Version Information
|
||||
- **Current Version**: 1.13.7
|
||||
- **Latest UI Update**: v1.9.5 (UI/UX Overhaul)
|
||||
- **Latest Fix**: UI Flickering Resolution
|
||||
|
||||
---
|
||||
|
||||
*For the most up-to-date information, check the [CHANGELOG.md](CHANGELOG.md) and [README.md](README.md) files.*
|
||||
Reference in New Issue
Block a user