13 KiB

Raw Permalink Blame History

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

# 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

# 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

# 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

# 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):

# 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

Spustite Jupyter v koreňovom adresári repozitára: jupyter notebook
Prejdite do požadovaného priečinka lekcie
Otvorte súbory .ipynb na prácu s cvičeniami
Notebooky sú samostatné, obsahujú vysvetlenia a bunky s kódom
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

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

# 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

# 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:

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

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:

Vytvorte zdroj Azure Static Web App
Pripojte sa k GitHub repozitáru
Konfigurujte nastavenia buildu:
- Umiestnenie aplikácie: quiz-app
- Umiestnenie výstupu: dist
GitHub Actions workflow automaticky nasadí pri pushi

Dokumentačná stránka

# 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

# 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

Lokálny vývoj: Nainštalujte Python, Jupyter, Node.js lokálne
GitHub Codespaces: Cloudové okamžité vývojové prostredie
VS Code Dev kontajnery: Lokálny vývoj založený na kontajneroch
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:

# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience

Zlyhania npm inštalácie:

# 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. 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.

13 KiB Raw Permalink Blame History