From 721088b54dc95085f719379195ec0fb9030d2942 Mon Sep 17 00:00:00 2001 From: Louis Mazin Date: Tue, 19 Aug 2025 20:15:49 +0200 Subject: [PATCH] readme --- README.md | 390 +++++++++++++++++++----------------------------------- 1 file changed, 138 insertions(+), 252 deletions(-) diff --git a/README.md b/README.md index 4ba575b..d947321 100644 --- a/README.md +++ b/README.md @@ -1,266 +1,152 @@ -# Python PyQt6 Application Template +# 🚀 HoDA - Python PyQt6 Application Template -A modern, feature-rich template for building desktop applications with PyQt6. This template provides a solid foundation with theming, internationalization, settings management, and a modular architecture. +Bienvenue ! Ce projet est **bien plus qu'un simple template** : c'est une boĂźte Ă  outils moderne pour crĂ©er rapidement des applications desktop Python Ă©lĂ©gantes, robustes et Ă©volutives. +Vous voulez coder, personnaliser, traduire, mettre Ă  jour, distribuer ? Tout est dĂ©jĂ  prĂȘt ! -## Features +--- -- **Modern UI Framework**: Built with PyQt6 for cross-platform compatibility -- **Theme System**: Dark and light themes with easy customization -- **Internationalization**: Multi-language support (English and French included) -- **Settings Management**: Persistent user preferences with QSettings -- **Modular Architecture**: Clean separation of concerns with managers and observers -- **Tabbed Interface**: Flexible tab widget system with customizable positioning -- **Window State Management**: Remembers window size, position, and maximized state -- **Email Integration**: Built-in suggestion/feedback system with secure email configuration -- **Build Automation**: Automated building with PyInstaller -- **Virtual Environment Management**: Automated environment setup +## ✹ FonctionnalitĂ©s clĂ©s -## Project Structure +- **Interface moderne (PyQt6)** : Responsive, stylĂ©e, et facile Ă  personnaliser. +- **ThĂšmes dynamiques** : Passez du clair au sombre en un clic, ou crĂ©ez le vĂŽtre ! +- **Multi-langues** : Français, anglais... et ajoutez-en autant que vous voulez. +- **ParamĂštres utilisateurs** : Tout est sauvegardĂ© (thĂšme, langue, taille de fenĂȘtre...). +- **Architecture modulaire** : Des managers pour chaque besoin, tout est organisĂ©. +- **Notifications automatiques** : Les widgets s'adaptent instantanĂ©ment aux changements. +- **Barre d’onglets flexible** : Ajoutez vos fenĂȘtres oĂč vous voulez, comme vous voulez. +- **SystĂšme de suggestion** : Vos utilisateurs peuvent vous Ă©crire directement depuis l’app. +- **Mise Ă  jour automatique** : TĂ©lĂ©chargez la derniĂšre version sans effort, avec barre de progression ! +- **Build & environnement** : Scripts pour tout automatiser, sur Windows, Linux, macOS. + +--- + +## đŸ—‚ïž Structure du projet ``` Template/ ├── app/ -│ ├── core/ # Core application managers -│ │ ├── main_manager.py # Singleton manager coordinator -│ │ ├── settings_manager.py # User settings and configuration -│ │ ├── theme_manager.py # Theme and styling management -│ │ ├── language_manager.py # Internationalization -│ │ └── observer_manager.py # Event notification system +│ ├── core/ # Managers (thĂšme, langue, update, etc.) │ ├── ui/ -│ │ ├── main_window.py # Main application window -│ │ ├── widgets/ # Custom widgets -│ │ │ └── tabs_widget.py # Customizable tab system -│ │ └── windows/ # Application windows -│ │ ├── settings_window.py -│ │ └── suggestion_window.py -│ └── utils/ -│ └── paths.py # Path utilities for resources +│ │ ├── widgets/ # Onglets, loading bar, etc. +│ │ └── windows/ # ParamĂštres, suggestion... +│ └── utils/ # Fonctions utilitaires ├── data/ -│ ├── assets/ # Icons and images -│ ├── lang/ # Language files (JSON) -│ ├── themes/ # Theme configuration files -│ └── others/ # Default settings -├── tools/ # Build and development tools -│ ├── build.bat/.sh/.command # Platform-specific build script -│ └── open.bat/.sh/.command # Platform-specific development setup -├── config.json # Application configuration -├── requirements.txt # Python dependencies -├── BUILD.spec # PyInstaller specification -└── main.py # Application entry point +│ ├── assets/ # IcĂŽnes, images +│ ├── lang/ # Traductions +│ ├── themes/ # ThĂšmes +│ └── others/ # ParamĂštres par dĂ©faut +├── tools/ # Scripts build/dev +├── config.json # Config principale +├── requirements.txt # DĂ©pendances +├── BUILD.spec # PyInstaller +└── main.py # Point d’entrĂ©e ``` -### Development Setup - -1. **Clone/Download** this template -2. **Configure** your application in `config.json`: - ```json - { - "app_name": "YourAppName", - "python_version": "YourPythonVersion", - "app_os": "Windows or Linux or Mac", - "app_version": "YourAppVersion", - "architecture": "x64 or x32", - "icon_path": "data/assets/icon.ico", - "main_script": "main.py" - } - ``` - -3. **Setup environment configuration**: - - Copy `.env.example` to `.env` - - Configure your Python path and email credentials: - ```env - # Python Configuration - PYTHON_PATH=C:/Path/To/Your/Python/python.exe - - # Email Configuration (optional) - EMAIL_ADDRESS=your_email@gmail.com - EMAIL_PASSWORD=your_app_password - EMAIL_SMTP_SERVER=smtp.gmail.com - EMAIL_SMTP_PORT=587 - ``` - - For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833) instead of your regular password - -4. **Run development environment**: - - **Windows**: `tools\open.bat` - - **Linux**: `tools/open.sh` - - **macOS**: `tools/open.command` - - This will: - - Create a virtual environment - - Install dependencies - - Open VS Code with proper environment - -### Building for Production - -- **Windows**: `tools\build.bat` -- **Linux**: `tools/build.sh` -- **macOS**: `tools/build.command` - -This creates a standalone executable in the `build/` directory. - -### Adding Themes - -Create JSON files in `data/themes/`. **Important**: Use the predefined color names as they are used throughout the application's styling system. - -```json -{ - "theme_name": "custom", - "colors": { - "background": "#FFFFFF", // Main background color - "background2": "#F5F5F5", // Secondary background - "background3": "#E0E0E0", // Tertiary background - "font_color": "#000000", // Text color - "selected_icon": "#000000", // Selected icon color - "unselected_icon": "#5D5A5A", // Unselected icon color - "selected_border_icon": "#000000", // Selected border color - "hover_icon": "#000000" // Hover state color - } -} -``` - -**Warning**: Do not change the color property names (`background`, `background2`, etc.) as they are hardcoded in the theme system. Only modify the hex color values. - -### Adding Languages - -Create JSON files in `data/lang/`. **Important**: Use the existing translation keys to ensure proper functionality. - -```json -{ - "lang_name": "Español", - "yes": "SĂ­", - "no": "No", - "language": "Idioma:", - "settings": "ConfiguraciĂłn", - "theme": "Tema:", - "dark_theme": "Tema Oscuro", - "light_theme": "Tema Claro", - "suggestion_text": "ÂżTienes una pregunta o idea para mejorar esta aplicaciĂłn?", - "suggestion_placeholder": "Escribe tu mensaje aquĂ­...", - "send_suggestion": "Enviar", - "sending": "Enviando...", - "success": "Éxito", - "error": "Error", - "suggestion_sent_success": "ÂĄTu mensaje ha sido enviado exitosamente!", - "suggestion_send_error": "Error al enviar el mensaje. IntĂ©ntalo de nuevo mĂĄs tarde.", - "email_credentials_error": "Credenciales de email no configuradas. Por favor configura tu email y contraseña en el archivo .env." -} -``` - -**Warning**: Do not change the translation keys (left side of the colon) as they are used throughout the application code. Only translate the values (right side). - -## Architecture - -### Manager Pattern - -The application uses a centralized manager system: - -- **MainManager**: Singleton coordinator for all managers -- **SettingsManager**: Handles user preferences and persistence -- **ThemeManager**: Manages themes and styling -- **LanguageManager**: Handles internationalization -- **ObserverManager**: Event notification system - -### Observer Pattern - -Components can subscribe to events: - -```python -self.observer_manager.subscribe(NotificationType.THEME, self.update_theme) -self.observer_manager.subscribe(NotificationType.LANGUAGE, self.update_language) -``` - -### Tab System - -The flexible tab widget supports multiple positioning options: - -```python -# Add a tab with custom positioning -self.side_menu.add_widget( - widget=your_widget, - button_text="", - icon_path=paths.get_asset_svg_path("icon_name"), - position=ButtonPosition.CENTER -) -``` - -## Email Integration - -The template includes a suggestion system with email capabilities. Configure in your `.env` file: - -**Security Note**: Never commit your `.env` file to version control. It's already included in `.gitignore`. - -For Gmail users: -- Enable 2-factor authentication -- Generate an App Password specifically for this application -- Use the App Password in the `EMAIL_PASSWORD` field - -## Customization - -### Adding New Windows - -1. Create window class inheriting from `QWidget` -2. Subscribe to language notifications -3. Add to main window tab system - -```python -class YourWindow(QWidget): - def __init__(self, parent=None): - super().__init__(parent) - self.main_manager = MainManager.get_instance() - # Subscribe to notifications - self.observer_manager.subscribe(NotificationType.LANGUAGE, self.update_language) - self.setup_ui() -``` - -### Custom Widgets - -Place custom widgets in `app/ui/widgets/` and follow the existing patterns for theme integration. - -## Dependencies - -- **PyQt6**: Modern GUI framework -- **pyinstaller**: Executable building -- **python-dotenv**: Environment variable management - -Add additional dependencies to `requirements.txt`. - -## Building - -The build system automatically: -- Creates virtual environments per architecture -- Installs dependencies -- Builds with PyInstaller -- Names executables with config.json -- Includes all assets and data files - -## Cross-Platform Notes - -The template supports multiple platforms with platform-specific scripts: -- **Windows**: Uses `.bat` files -- **Linux**: Uses `.sh` files -- **macOS**: Uses `.command` files - -Adjust config.json for your target platform. - -## License - -MIT License - see LICENSE file for details. - -## Contributing - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Test thoroughly -5. Submit a pull request - -## Support - -For issues or questions: -- Check existing issues -- Create detailed bug reports -- Include system information and error logs - --- -**Happy coding!** 🚀 \ No newline at end of file +## ⚡ DĂ©marrage Express + +1. **Configurez `config.json`** + (nom, version, OS, architecture, icĂŽne, dĂ©pĂŽt git...) + +2. **Copiez `.env.example` → `.env`** + (chemin Python, email, mot de passe...) + +3. **Lancez le dev** + - Windows : `tools\open.bat` + - Linux : `tools/open.sh` + - macOS : `tools/open.command` + +4. **Build en un clic** + - Windows : `tools\build.bat` + - Linux : `tools/build.sh` + - macOS : `tools/build.command` + +--- + +## 🎹 ThĂšmes & 🌍 Langues + +- **ThĂšmes** : Ajoutez vos fichiers dans `data/themes/` (JSON). + Changez les couleurs, crĂ©ez votre ambiance ! +- **Langues** : Ajoutez vos fichiers dans `data/lang/` (JSON). + Traduisez tout, c’est instantanĂ©. + +--- + +## đŸ§© Managers & Architecture + +- **MainManager** : Le chef d’orchestre. +- **SettingsManager** : Les prĂ©fĂ©rences utilisateur. +- **ThemeManager** : Les couleurs et le style. +- **LanguageManager** : Les textes traduits. +- **AlertManager** : Les messages, confirmations, erreurs. +- **UpdateManager** : Les mises Ă  jour automatiques. +- **ObserverManager** : Les notifications internes. + +--- + +## 🔄 Mise Ă  jour automatique + +- VĂ©rifie la derniĂšre version sur le dĂ©pĂŽt Git Ă  chaque dĂ©marrage. +- Propose la mise Ă  jour si disponible. +- TĂ©lĂ©charge le bon fichier selon votre OS/architecture. +- Affiche une barre de progression stylĂ©e. +- Lance la nouvelle version automatiquement ! + +--- + +## 💡 Suggestions & Feedback + +- FenĂȘtre dĂ©diĂ©e pour envoyer vos idĂ©es ou questions par email. +- SĂ©curisĂ© via `.env`. +- Gestion des erreurs/succĂšs avec AlertManager. + +--- + +## đŸ› ïž Ajouter vos fenĂȘtres & widgets + +- CrĂ©ez une classe hĂ©ritant de `QWidget`. +- Ajoutez-la dans la barre d’onglets (`TabsWidget`). +- Abonnez-vous aux notifications pour la langue/le thĂšme. + +--- + +## 📩 DĂ©pendances + +- **PyQt6** : GUI moderne. +- **pyinstaller** : Build d’exĂ©cutables. +- **python-dotenv** : Variables d’environnement. +- **requests** : RequĂȘtes HTTP (update). + +--- + +## 🔒 SĂ©curitĂ© + +- **Ne versionnez jamais `.env`** (dĂ©jĂ  dans `.gitignore`). +- Utilisez un mot de passe d’application pour Gmail. + +--- + +## 📝 Licence + +MIT License. Voir le fichier LICENSE. + +--- + +## đŸ€ Contribution + +1. Forkez le dĂ©pĂŽt +2. CrĂ©ez une branche +3. Proposez vos modifications via pull request + +--- + +## 🆘 Support + +- Ouvrez une issue sur le dĂ©pĂŽt +- PrĂ©cisez votre OS, version Python, logs d’erreur + +--- + +**Ce template est fait pour vous faire gagner du temps et coder avec plaisir ! +Testez-le, amĂ©liorez-le, partagez-le 🚀** \ No newline at end of file