# AGENTS.md ## Přehled projektu Data Science for Beginners je komplexní desetitýdenní kurz s 20 lekcemi vytvořený týmem Microsoft Azure Cloud Advocates. Tento repozitář slouží jako vzdělávací zdroj, který učí základní koncepty datové vědy prostřednictvím projektově orientovaných lekcí, včetně Jupyter notebooků, interaktivních kvízů a praktických úkolů. **Klíčové technologie:** - **Jupyter Notebooks**: Hlavní výukové médium využívající Python 3 - **Python knihovny**: pandas, numpy, matplotlib pro analýzu a vizualizaci dat - **Vue.js 2**: Aplikace pro kvízy (složka quiz-app) - **Docsify**: Generátor dokumentačních stránek pro offline přístup - **Node.js/npm**: Správa balíčků pro JavaScript komponenty - **Markdown**: Veškerý obsah lekcí a dokumentace **Architektura:** - Vzdělávací repozitář s podporou více jazyků a rozsáhlými překlady - Strukturováno do modulů lekcí (1-Introduction až 6-Data-Science-In-Wild) - Každá lekce obsahuje README, notebooky, úkoly a kvízy - Samostatná aplikace Vue.js pro hodnocení před a po lekci - Podpora GitHub Codespaces a vývojových kontejnerů VS Code ## Příkazy pro nastavení ### Nastavení repozitáře ```bash # Clone the repository (if not already cloned) git clone https://github.com/microsoft/Data-Science-For-Beginners.git cd Data-Science-For-Beginners ``` ### Nastavení Python prostředí ```bash # Create a virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install common data science libraries (no requirements.txt exists) pip install jupyter pandas numpy matplotlib seaborn scikit-learn ``` ### Nastavení aplikace pro kvízy ```bash # Navigate to quiz app cd quiz-app # Install dependencies npm install # Start development server npm run serve # Build for production npm run build # Lint and fix files npm run lint ``` ### Dokumentační server Docsify ```bash # Install Docsify globally npm install -g docsify-cli # Serve documentation locally docsify serve # Documentation will be available at localhost:3000 ``` ### Nastavení projektů pro vizualizaci Pro projekty vizualizace, jako je meaningful-visualizations (lekce 13): ```bash # Navigate to starter or solution folder cd 3-Data-Visualization/13-meaningful-visualizations/starter # Install dependencies npm install # Start development server npm run serve # Build for production npm run build # Lint files npm run lint ``` ## Pracovní postup vývoje ### Práce s Jupyter notebooky 1. Spusťte Jupyter v kořenovém adresáři repozitáře: `jupyter notebook` 2. Přejděte do složky požadované lekce 3. Otevřete soubory `.ipynb` a pracujte na cvičeních 4. Notebooky jsou samostatné, obsahují vysvětlení a buňky s kódem 5. Většina notebooků používá pandas, numpy a matplotlib - ujistěte se, že jsou nainstalovány ### Struktura lekce Každá lekce obvykle obsahuje: - `README.md` - Hlavní obsah lekce s teorií a příklady - `notebook.ipynb` - Praktická cvičení v Jupyter notebooku - `assignment.ipynb` nebo `assignment.md` - Praktické úkoly - Složku `solution/` - Notebooky a kód s řešeními - Složku `images/` - Podpůrné vizuální materiály ### Vývoj aplikace pro kvízy - Aplikace Vue.js 2 s podporou hot-reload během vývoje - Kvízy jsou uloženy ve složce `quiz-app/src/assets/translations/` - Každý jazyk má vlastní složku s překlady (en, fr, es atd.) - Číslování kvízů začíná od 0 a končí na 39 (celkem 40 kvízů) ### Přidávání překladů - Překlady se ukládají do složky `translations/` v kořenovém adresáři repozitáře - Každý jazyk má kompletní strukturu lekcí zrcadlenou z angličtiny - Automatizované překlady prostřednictvím GitHub Actions (co-op-translator.yml) ## Pokyny k testování ### Testování aplikace pro kvízy ```bash cd quiz-app # Run lint checks npm run lint # Test build process npm run build # Manual testing: Start dev server and verify quiz functionality npm run serve ``` ### Testování notebooků - Pro notebooky neexistuje žádný automatizovaný testovací rámec - Ruční ověření: Spusťte všechny buňky v pořadí a ověřte, že nedochází k chybám - Ověřte, že jsou přístupné datové soubory a že výstupy jsou správně generovány - Zkontrolujte, zda se vizualizace správně vykreslují ### Testování dokumentace ```bash # Verify Docsify renders correctly docsify serve # Check for broken links manually by navigating through content # Verify all lesson links work in the rendered documentation ``` ### Kontroly kvality kódu ```bash # Vue.js projects (quiz-app and visualization projects) cd quiz-app # or visualization project folder npm run lint # Python notebooks - manual verification recommended # Ensure imports work and cells execute without errors ``` ## Pokyny ke stylu kódu ### Python (Jupyter notebooky) - Dodržujte pokyny ke stylu PEP 8 pro Python kód - Používejte jasné názvy proměnných, které vysvětlují analyzovaná data - Přidávejte buňky Markdown s vysvětlením před buňkami s kódem - Udržujte buňky s kódem zaměřené na jednotlivé koncepty nebo operace - Používejte pandas pro manipulaci s daty, matplotlib pro vizualizaci - Běžný vzor importu: ```python import pandas as pd import numpy as np import matplotlib.pyplot as plt ``` ### JavaScript/Vue.js - Dodržujte pokyny ke stylu Vue.js 2 a osvědčené postupy - Konfigurace ESLint ve `quiz-app/package.json` - Používejte Vue komponenty s jedním souborem (.vue soubory) - Udržujte architekturu založenou na komponentách - Spusťte `npm run lint` před odesláním změn ### Dokumentace v Markdownu - Používejte jasnou hierarchii nadpisů (# ## ### atd.) - Přidávejte bloky kódu s určením jazyka - Přidávejte alternativní texty k obrázkům - Odkazujte na související lekce a zdroje - Udržujte rozumnou délku řádků pro čitelnost ### Organizace souborů - Obsah lekcí ve složkách s čísly (01-defining-data-science atd.) - Řešení ve vyhrazených podsložkách `solution/` - Překlady zrcadlí anglickou strukturu ve složce `translations/` - Datové soubory uchovávejte ve složce `data/` nebo ve složkách specifických pro lekce ## Sestavení a nasazení ### Nasazení aplikace pro kvízy ```bash cd quiz-app # Build production version npm run build # Output is in dist/ folder # Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.) ``` ### Nasazení Azure Static Web Apps Aplikace quiz-app může být nasazena na Azure Static Web Apps: 1. Vytvořte prostředek Azure Static Web App 2. Připojte se k repozitáři na GitHubu 3. Nakonfigurujte nastavení sestavení: - Umístění aplikace: `quiz-app` - Umístění výstupu: `dist` 4. GitHub Actions workflow automaticky nasadí při push ### Dokumentační web ```bash # Build PDF from Docsify (optional) npm run convert # Docsify documentation is served directly from markdown files # No build step required for deployment # Deploy repository to static hosting with Docsify ``` ### GitHub Codespaces - Repozitář obsahuje konfiguraci vývojového kontejneru - Codespaces automaticky nastaví prostředí pro Python a Node.js - Otevřete repozitář v Codespace prostřednictvím GitHub UI - Všechny závislosti se nainstalují automaticky ## Pokyny pro pull requesty ### Před odesláním ```bash # For Vue.js changes in quiz-app cd quiz-app npm run lint npm run build # Test changes locally npm run serve ``` ### Formát názvu PR - Používejte jasné, popisné názvy - Formát: `[Komponenta] Stručný popis` - Příklady: - `[Lekce 7] Oprava chyby importu v Python notebooku` - `[Aplikace pro kvízy] Přidání německého překladu` - `[Dokumentace] Aktualizace README s novými předpoklady` ### Požadované kontroly - Ujistěte se, že veškerý kód běží bez chyb - Ověřte, že notebooky se kompletně spustí - Zkontrolujte, že aplikace Vue.js se úspěšně sestaví - Ověřte, že odkazy v dokumentaci fungují - Otestujte aplikaci pro kvízy, pokud byla upravena - Ověřte, že překlady zachovávají konzistentní strukturu ### Pokyny pro přispívání - Dodržujte stávající styl kódu a vzory - Přidávejte vysvětlující komentáře ke složitější logice - Aktualizujte příslušnou dokumentaci - Testujte změny napříč různými moduly lekcí, pokud je to relevantní - Prostudujte si soubor CONTRIBUTING.md ## Další poznámky ### Běžně používané knihovny - **pandas**: Manipulace a analýza dat - **numpy**: Numerické výpočty - **matplotlib**: Vizualizace a vykreslování dat - **seaborn**: Statistická vizualizace dat (některé lekce) - **scikit-learn**: Strojové učení (pokročilé lekce) ### Práce s datovými soubory - Datové soubory jsou umístěny ve složce `data/` nebo ve složkách specifických pro lekce - Většina notebooků očekává datové soubory v relativních cestách - Hlavním formátem dat jsou soubory CSV - Některé lekce používají JSON pro příklady nerelačních dat ### Podpora více jazyků - Přes 40 jazykových překladů prostřednictvím automatizovaných GitHub Actions - Workflow překladu ve `.github/workflows/co-op-translator.yml` - Překlady ve složce `translations/` s jazykovými kódy - Překlady kvízů ve složce `quiz-app/src/assets/translations/` ### Možnosti vývojového prostředí 1. **Lokální vývoj**: Nainstalujte Python, Jupyter, Node.js lokálně 2. **GitHub Codespaces**: Cloudové okamžité vývojové prostředí 3. **VS Code Dev Containers**: Lokální vývoj založený na kontejnerech 4. **Binder**: Spuštění notebooků v cloudu (pokud je nakonfigurováno) ### Pokyny k obsahu lekcí - Každá lekce je samostatná, ale staví na předchozích konceptech - Kvízy před lekcí testují předchozí znalosti - Kvízy po lekci posilují učení - Úkoly poskytují praktické procvičení - Sketchnotes poskytují vizuální shrnutí ### Řešení běžných problémů **Problémy s jádrem Jupyter:** ```bash # Ensure correct kernel is installed python -m ipykernel install --user --name=datascience ``` **Chyby při instalaci npm:** ```bash # Clear npm cache and retry npm cache clean --force rm -rf node_modules package-lock.json npm install ``` **Chyby importu v notebookách:** - Ověřte, že jsou nainstalovány všechny požadované knihovny - Zkontrolujte kompatibilitu verze Pythonu (doporučeno Python 3.7+) - Ujistěte se, že je aktivováno virtuální prostředí **Docsify se nenačítá:** - Ověřte, že spouštíte ze základního adresáře repozitáře - Zkontrolujte, zda existuje `index.html` - Ujistěte se, že máte správný přístup k síti (port 3000) ### Úvahy o výkonu - Velké datové sady mohou trvat déle na načtení v notebookách - Vykreslování vizualizací může být pomalé u složitých grafů - Vývojový server Vue.js umožňuje rychlé iterace díky hot-reload - Produkční sestavení jsou optimalizována a minimalizována ### Bezpečnostní poznámky - Do repozitáře by neměla být ukládána citlivá data nebo přihlašovací údaje - Používejte proměnné prostředí pro jakékoli API klíče v cloudových lekcích - Lekce související s Azure mohou vyžadovat přihlašovací údaje k účtu Azure - Udržujte závislosti aktuální kvůli bezpečnostním opravám ## Přispívání k překladům - Automatizované překlady jsou spravovány prostřednictvím GitHub Actions - Manuální opravy jsou vítány pro zajištění přesnosti překladů - Dodržujte stávající strukturu složek pro překlady - Aktualizujte odkazy na kvízy tak, aby zahrnovaly parametr jazyka: `?loc=fr` - Testujte přeložené lekce, zda se správně zobrazují ## Související zdroje - Hlavní kurikulum: https://aka.ms/datascience-beginners - Microsoft Learn: https://docs.microsoft.com/learn/ - Student Hub: https://docs.microsoft.com/learn/student-hub - Diskusní fórum: https://github.com/microsoft/Data-Science-For-Beginners/discussions - Další kurikula od Microsoftu: ML for Beginners, AI for Beginners, Web Dev for Beginners ## Údržba projektu - Pravidelné aktualizace pro udržení aktuálnosti obsahu - Příspěvky komunity jsou vítány - Problémy jsou sledovány na GitHubu - PR jsou kontrolovány správci kurikula - Měsíční revize a aktualizace obsahu --- **Prohlášení**: Tento dokument byl přeložen pomocí služby AI pro překlad [Co-op Translator](https://github.com/Azure/co-op-translator). I když se snažíme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho rodném jazyce by měl být považován za autoritativní zdroj. Pro důležité informace se doporučuje profesionální lidský překlad. Nejsme zodpovědní za jakékoli nedorozumění nebo nesprávné interpretace vyplývající z použití tohoto překladu.