Data-Science-For-Beginners/translations/sk/AGENTS.md

# AGENTS.md

## Prehľad projektu

Data Science for Beginners je komplexný 10-týždňový, 20-lekciový kurz vytvorený tímom Microsoft Azure Cloud Advocates. Tento repozitár je vzdelávací zdroj, ktorý učí základné koncepty dátovej vedy prostredníctvom lekcií založených na projektoch, vrátane Jupyter notebookov, interaktívnych kvízov a praktických úloh.

**Kľúčové technológie:**
- **Jupyter Notebooks**: Hlavné médium na učenie pomocou Pythonu 3
- **Python knižnice**: pandas, numpy, matplotlib na analýzu a vizualizáciu dát
- **Vue.js 2**: Aplikácia na kvízy (priečinok quiz-app)
- **Docsify**: Generátor dokumentačných stránok pre offline prístup
- **Node.js/npm**: Správa balíkov pre JavaScript komponenty
- **Markdown**: Všetok obsah lekcií a dokumentácia

**Architektúra:**
- Vzdelávací repozitár s podporou viacerých jazykov a rozsiahlymi prekladmi
- Štruktúrovaný do modulov lekcií (1-Úvod až 6-Dátová veda v praxi)
- Každá lekcia obsahuje README, notebooky, úlohy a kvízy
- Samostatná aplikácia Vue.js na hodnotenie pred/po lekciách
- Podpora GitHub Codespaces a VS Code dev kontajnerov

## Príkazy na nastavenie

### Nastavenie repozitára
```bash
# Clone the repository (if not already cloned)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners
```

### Nastavenie Python prostredia
```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
```

### Nastavenie aplikácie na 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
```

### Docsify dokumentačný server
```bash
# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000
```

### Nastavenie projektov na vizualizáciu
Pre projekty na vizualizáciu, ako napríklad meaningful-visualizations (lekcia 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ývoja

### Práca s Jupyter notebookmi
1. Spustite Jupyter v koreňovom adresári repozitára: `jupyter notebook`
2. Prejdite do požadovaného priečinka lekcie
3. Otvorte súbory `.ipynb` na prácu s cvičeniami
4. Notebooky sú samostatné, obsahujú vysvetlenia a bunky s kódom
5. Väčšina notebookov používa pandas, numpy a matplotlib - uistite sa, že sú nainštalované

### Štruktúra lekcií
Každá lekcia zvyčajne obsahuje:
- `README.md` - Hlavný obsah lekcie s teóriou a príkladmi
- `notebook.ipynb` - Praktické cvičenia v Jupyter notebooku
- `assignment.ipynb` alebo `assignment.md` - Úlohy na precvičenie
- Priečinok `solution/` - Notebooky a kód s riešeniami
- Priečinok `images/` - Podporné vizuálne materiály

### Vývoj aplikácie na kvízy
- Aplikácia Vue.js 2 s hot-reload počas vývoja
- Kvízy sú uložené v `quiz-app/src/assets/translations/`
- Každý jazyk má vlastný priečinok s prekladmi (en, fr, es, atď.)
- Číslovanie kvízov začína od 0 a pokračuje až do 39 (celkovo 40 kvízov)

### Pridávanie prekladov
- Preklady sa ukladajú do priečinka `translations/` v koreňovom adresári repozitára
- Každý jazyk má kompletnú štruktúru lekcií zrkadlenú z angličtiny
- Automatizované preklady prostredníctvom GitHub Actions (co-op-translator.yml)

## Pokyny na testovanie

### Testovanie aplikácie na 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
```

### Testovanie notebookov
- Pre notebooky neexistuje automatizovaný testovací rámec
- Manuálna validácia: Spustite všetky bunky postupne, aby ste sa uistili, že neobsahujú chyby
- Overte dostupnosť dátových súborov a správnosť generovaných výstupov
- Skontrolujte, či sa vizualizácie správne zobrazujú

### Testovanie dokumentácie
```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 pre štýl kódu

### Python (Jupyter notebooky)
- Dodržiavajte štýlové pokyny PEP 8 pre Python kód
- Používajte jasné názvy premenných, ktoré vysvetľujú analyzované dáta
- Pred bunkami s kódom pridávajte bunky s vysvetleniami v Markdown
- Udržujte bunky s kódom zamerané na jednotlivé koncepty alebo operácie
- Používajte pandas na manipuláciu s dátami, matplotlib na vizualizáciu
- Bežný importovací vzor:
  ```python
  import pandas as pd
  import numpy as np
  import matplotlib.pyplot as plt
  ```


### JavaScript/Vue.js
- Dodržiavajte štýlové pokyny Vue.js 2 a osvedčené postupy
- Konfigurácia ESLint v `quiz-app/package.json`
- Používajte Vue komponenty s jedným súborom (.vue súbory)
- Zachovávajte architektúru založenú na komponentoch
- Pred odoslaním zmien spustite `npm run lint`

### Dokumentácia v Markdown
- Používajte jasnú hierarchiu nadpisov (# ## ### atď.)
- Zahrňte bloky kódu so špecifikáciou jazyka
- Pridávajte alt text pre obrázky
- Odkazujte na súvisiace lekcie a zdroje
- Udržujte rozumnú dĺžku riadkov pre čitateľnosť

### Organizácia súborov
- Obsah lekcií v očíslovaných priečinkoch (01-defining-data-science, atď.)
- Riešenia v samostatných podpriečinkoch `solution/`
- Preklady zrkadlia anglickú štruktúru v priečinku `translations/`
- Dátové súbory uchovávajte v priečinku `data/` alebo v priečinkoch špecifických pre lekcie

## Build a nasadenie

### Nasadenie aplikácie na 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.)
```

### Nasadenie Azure Static Web Apps
Aplikáciu quiz-app je možné nasadiť na Azure Static Web Apps:
1. Vytvorte zdroj Azure Static Web App
2. Pripojte sa k GitHub repozitáru
3. Konfigurujte nastavenia buildu:
   - Umiestnenie aplikácie: `quiz-app`
   - Umiestnenie výstupu: `dist`
4. GitHub Actions workflow automaticky nasadí pri pushi

### Dokumentačná stránka
```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ár obsahuje konfiguráciu dev kontajnera
- Codespaces automaticky nastaví Python a Node.js prostredie
- Otvorte repozitár v Codespace cez GitHub UI
- Všetky závislosti sa nainštalujú automaticky

## Pokyny pre pull requesty

### Pred odoslaní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žívajte jasné, popisné názvy
- Formát: `[Komponent] Stručný popis`
- Príklady:
  - `[Lekcia 7] Oprava chyby importu v Python notebooku`
  - `[Aplikácia na kvízy] Pridanie nemeckého prekladu`
  - `[Dokumentácia] Aktualizácia README s novými predpokladmi`

### Požadované kontroly
- Uistite sa, že všetok kód beží bez chýb
- Overte, že notebooky sa vykonávajú úplne
- Skontrolujte, či aplikácie Vue.js úspešne buildujú
- Overte funkčnosť odkazov v dokumentácii
- Otestujte aplikáciu na kvízy, ak bola upravená
- Overte, že preklady zachovávajú konzistentnú štruktúru

### Pokyny pre prispievanie
- Dodržiavajte existujúci štýl kódu a vzory
- Pridávajte vysvetľujúce komentáre k zložitej logike
- Aktualizujte relevantnú dokumentáciu
- Testujte zmeny naprieč rôznymi modulmi lekcií, ak je to vhodné
- Preštudujte si súbor CONTRIBUTING.md

## Ďalšie poznámky

### Bežne používané knižnice
- **pandas**: Manipulácia a analýza dát
- **numpy**: Numerické výpočty
- **matplotlib**: Vizualizácia a grafy
- **seaborn**: Štatistická vizualizácia dát (niektoré lekcie)
- **scikit-learn**: Strojové učenie (pokročilé lekcie)

### Práca s dátovými súbormi
- Dátové súbory sa nachádzajú v priečinku `data/` alebo v priečinkoch špecifických pre lekcie
- Väčšina notebookov očakáva dátové súbory v relatívnych cestách
- Primárnym formátom dát sú CSV súbory
- Niektoré lekcie používajú JSON pre príklady nerelačných dát

### Podpora viacerých jazykov
- Viac ako 40 jazykových prekladov prostredníctvom automatizovaných GitHub Actions
- Workflow pre preklady v `.github/workflows/co-op-translator.yml`
- Preklady v priečinku `translations/` s jazykovými kódmi
- Preklady kvízov v `quiz-app/src/assets/translations/`

### Možnosti vývojového prostredia
1. **Lokálny vývoj**: Nainštalujte Python, Jupyter, Node.js lokálne
2. **GitHub Codespaces**: Cloudové okamžité vývojové prostredie
3. **VS Code Dev kontajnery**: Lokálny vývoj založený na kontajneroch
4. **Binder**: Spustenie notebookov v cloude (ak je nakonfigurované)

### Pokyny pre obsah lekcií
- Každá lekcia je samostatná, ale stavia na predchádzajúcich konceptoch
- Kvízy pred lekciou testujú predchádzajúce znalosti
- Kvízy po lekcii posilňujú učenie
- Úlohy poskytujú praktické precvičenie
- Sketchnotes poskytujú vizuálne zhrnutia

### Riešenie bežných problémov

**Problémy s Jupyter kernelom:**
```bash
# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience
```

**Zlyhania npm inštalácie:**
```bash
# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

**Chyby importu v notebookoch:**
- Overte, že všetky požadované knižnice sú nainštalované
- Skontrolujte kompatibilitu verzie Pythonu (odporúčaný Python 3.7+)
- Uistite sa, že virtuálne prostredie je aktivované

**Docsify sa nenačítava:**
- Overte, že server spúšťate z koreňového adresára repozitára
- Skontrolujte, či existuje súbor `index.html`
- Uistite sa, že máte správny sieťový prístup (port 3000)

### Úvahy o výkone
- Veľké dátové súbory môžu trvať dlhšie na načítanie v notebookoch
- Vizualizácie môžu byť pomalé pri zložitých grafoch
- Dev server Vue.js umožňuje hot-reload pre rýchlu iteráciu
- Produkčné buildy sú optimalizované a minifikované

### Poznámky k bezpečnosti
- Do repozitára by nemali byť nahrávané citlivé údaje alebo poverenia
- Používajte environmentálne premenné pre akékoľvek API kľúče v cloudových lekciách
- Lekcie súvisiace s Azure môžu vyžadovať poverenia k Azure účtu
- Udržujte závislosti aktualizované kvôli bezpečnostným opravám

## Prispievanie k prekladom
- Automatizované preklady sú spravované prostredníctvom GitHub Actions
- Manuálne opravy sú vítané pre presnosť prekladov
- Dodržiavajte existujúcu štruktúru priečinkov pre preklady
- Aktualizujte odkazy na kvízy, aby obsahovali jazykový parameter: `?loc=fr`
- Testujte preložené lekcie na správne zobrazenie

## Súvisiace zdroje
- Hlavný kurz: https://aka.ms/datascience-beginners
- Microsoft Learn: https://docs.microsoft.com/learn/
- Študentské centrum: https://docs.microsoft.com/learn/student-hub
- Diskusné fórum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
- Ďalšie Microsoft kurzy: ML for Beginners, AI for Beginners, Web Dev for Beginners

## Údržba projektu
- Pravidelné aktualizácie na udržanie aktuálneho obsahu
- Príspevky od komunity sú vítané
- Problémy sú sledované na GitHube
- PR sú kontrolované správcami kurzu
- Mesačné kontroly obsahu a aktualizácie

---

**Upozornenie**:  
Tento dokument bol preložený pomocou služby AI prekladu [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, upozorňujeme, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu.