From 70a77d4cd1fd2d20aee37f0f04f0047af1128981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Doubravsk=C3=BD?= Date: Mon, 25 May 2026 18:03:41 +0200 Subject: [PATCH] Rewrite README to describe the documentation repository --- README.md | 201 +++++++++++------------------------------------------- 1 file changed, 41 insertions(+), 160 deletions(-) diff --git a/README.md b/README.md index 277179a..b2b3069 100644 --- a/README.md +++ b/README.md @@ -1,174 +1,55 @@ -# 🏷️ Tagger +# Dokumentace -Desktopová aplikace pro správu a organizaci souborů pomocí hierarchických tagů (štítků). +Personal development documentation — guidelines, conventions, and templates for my projects, structured for use with AI coding assistants. -## ✨ Hlavní funkce +## Purpose -- 📁 Rekurzivní procházení složek -- 🏷️ Hierarchické tagy (kategorie/název) -- 🔍 Filtrování podle tagů a textu -- 💾 Metadata v JSON souborech (.!tag) -- 🎬 Automatická detekce rozlišení videí (ffprobe) -- 🎨 Dvě verze GUI: klasické a moderní (qBittorrent-style) +This repository is the single source of truth for how I develop software. AI assistants (Claude Code, Cursor, Copilot) are given these documents at the start of each session to understand my conventions before touching any code. -## 🚀 Rychlý start - -```bash -# Instalace závislostí -poetry install - -# Spuštění (moderní GUI) -poetry run python Tagger_modern.py - -# Nebo klasické GUI -poetry run python Tagger.py -``` - -## 📸 Screenshot - -### Moderní GUI (qBittorrent-style) -``` -┌─────────────────────────────────────────────────────┐ -│ 📁 Otevřít │ 🔄 │ 🏷️ │ 📅 🔍 [____] Toolbar -├────────────┬────────────────────────────────────────┤ -│ 📂 Štítky │ Název │Datum│Štítky│Velikost │ -│ ├─📁 Stav │ file1.txt│2025 │HD │1.2 MB │ -│ │ ☑ Nové │ file2.mp4│ │4K │15 MB │ -│ ├─📁 Video│ file3.jpg│ │RAW │845 KB │ -│ │ ☐ HD │ │ -├────────────┴────────────────────────────────────────┤ -│ Připraven 3 vybráno │ 125 souborů │ -└─────────────────────────────────────────────────────┘ -``` - -## 🎯 Použití - -1. **Otevři složku** - Načti soubory ze složky (rekurzivně) -2. **Vytvoř tagy** - Hierarchická struktura (kategorie → tagy) -3. **Přiřaď tagy** - Označ soubory, vyber tagy -4. **Filtruj** - Klikni na tagy pro filtrování souborů -5. **Vyhledávej** - Textové vyhledávání v názvech - -## ⌨️ Keyboard Shortcuts (moderní GUI) - -- `Ctrl+O` - Otevřít složku -- `Ctrl+T` - Přiřadit tagy -- `Ctrl+D` - Nastavit datum -- `F5` - Refresh -- `Del` - Smazat z indexu - -## 🏗️ Architektura +## Structure ``` -┌─────────────────────────────────┐ -│ Presentation (UI) │ ← Tkinter GUI -├─────────────────────────────────┤ -│ Business Logic │ ← FileManager, TagManager -├─────────────────────────────────┤ -│ Data Layer │ ← File, Tag models -├─────────────────────────────────┤ -│ Persistence │ ← JSON .!tag soubory -└─────────────────────────────────┘ +Dokumentace/ +├── Claude/ # AI assistant configuration +│ ├── CLAUDE.md # Claude Code session instructions +│ ├── AGENTS.md # Rules for all AI assistants +│ └── skills/ # Custom Claude Code skills +│ +├── Python/ # Python development guidelines +│ ├── DESIGN_DOCUMENT.md # Guidelines for Python applications +│ ├── DESIGN_DOCUMENT_MODULE.md # Guidelines for Python libraries +│ ├── TEMPLATE.md # New project template specification +│ └── prebuild.py # Pre-build script (PyInstaller) +│ +├── Project template/ # Reusable files for new projects +│ ├── CHANGELOG.md # Changelog template +│ └── PROJECT.md # Project documentation template +│ +└── Zscaler/ # Corporate network setup + ├── NODE_EXTRA_CA_CERTS.md # Instructions for Zscaler cert + └── ZscalerRootCertificate-2048-SHA256.crt ``` -## 📁 Struktura projektu +## AI Coding Workflow -``` -Tagger/ -├── Tagger.py # Entry point (klasické GUI) -├── Tagger_modern.py # Entry point (moderní GUI) -├── PROJECT_NOTES.md # ⭐ Kompletní dokumentace -├── src/ -│ ├── core/ # Business logika -│ │ ├── file.py -│ │ ├── tag.py -│ │ ├── file_manager.py -│ │ └── tag_manager.py -│ └── ui/ -│ ├── gui.py # Klasické GUI -│ └── gui_modern.py # Moderní GUI -└── tests/ # 116 testů -``` +Each project references these documents so AI assistants operate within consistent rules: -## 🧪 Testování +- **AGENTS.md** — language-agnostic rules: dependency management, testing, logging, git, versioning +- **DESIGN_DOCUMENT.md** — Python-specific: code style, tooling (Ruff, mypy, pytest, Poetry), project structure, logging with loguru, distribution via PyInstaller +- **DESIGN_DOCUMENT_MODULE.md** — same as above, adapted for Python libraries (no sinks, no `.env`, PyPI distribution) -```bash -# Všechny testy (116 testů, 100% core coverage) -poetry run pytest tests/ -v +## Languages Covered -# S coverage report -poetry run pytest tests/ --cov=src/core --cov-report=html -``` +| Language | Guidelines | +|----------|-----------| +| Python (application) | `Python/DESIGN_DOCUMENT.md` | +| Python (library) | `Python/DESIGN_DOCUMENT_MODULE.md` | -## 📝 Dokumentace +## Key Conventions -**Veškerá dokumentace je v jednom souboru:** - -👉 **[PROJECT_NOTES.md](PROJECT_NOTES.md)** ⭐ - -Obsahuje: -- Kompletní dokumentaci projektu -- Architektonická rozhodnutí (ADR) -- Coding standards -- Git workflow -- Known issues & TODO -- Debugování tipy -- Pravidla pro AI asistenty - -## 🛠️ Technologie - -- **Python:** 3.12 -- **GUI:** Tkinter (standard library) -- **Dependencies:** Pillow (PIL) -- **Package manager:** Poetry -- **Testing:** pytest - -## 📊 Metriky - -- **Řádky kódu:** ~1060 Python LOC -- **Testy:** 116 (všechny ✅) -- **Test coverage:** 100% core modulů -- **GUI verze:** 2 (klasická + moderní) - -## 🎯 Design Decisions - -### Proč JSON místo databáze? -- ✅ Jednoduchý backup (copy složky) -- ✅ Git-friendly (plain text) -- ✅ Portable (žádné DB dependencies) -- ✅ Metadata zůstanou při přesunu souboru - -### Proč Tkinter? -- ✅ Standard library (žádné extra deps) -- ✅ Cross-platform -- ✅ Dobře dokumentované - -### Proč Poetry? -- ✅ Deterministické buildy (poetry.lock) -- ✅ Dev dependencies oddělené -- ✅ Moderní nástroj - -## 🐛 Known Issues - -- Git merge konflikty s poetry.lock při merge devel→feature -- Dlouhé operace (ffprobe) blokují UI - TODO: threading - -## 🚀 Plánované features - -- [ ] Progress bar pro dlouhé operace -- [ ] Undo/Redo mechanismus -- [ ] Export do CSV/Excel -- [ ] Dark mode theme -- [ ] Drag & drop souborů - -## 📄 License - -MIT License - -## 👤 Autor - -honza - ---- - -**Pro detailní dokumentaci viz [PROJECT_NOTES.md](PROJECT_NOTES.md)** +- **Python tooling:** Poetry · Ruff · mypy · pytest · loguru +- **No print() for debugging** — loguru everywhere +- **Type hints required** on all functions +- **Tests:** pytest only, no unittest, no mocks of the database +- **Versioning:** semantic, always ask before bumping +- **Secrets:** `.env` + `python-dotenv`, never committed