AGENTS.md

Огляд проєкту

Data Science for Beginners — це комплексна навчальна програма на 10 тижнів, що складається з 20 уроків, створена командою Microsoft Azure Cloud Advocates. Репозиторій є навчальним ресурсом, який викладає основні концепції науки про дані через проєктно-орієнтовані уроки, включаючи Jupyter ноутбуки, інтерактивні вікторини та практичні завдання.

Основні технології:

Jupyter Notebooks: Основний навчальний інструмент з використанням Python 3
Бібліотеки Python: pandas, numpy, matplotlib для аналізу даних та візуалізації
Vue.js 2: Додаток для вікторин (папка quiz-app)
Docsify: Генератор сайту документації для офлайн-доступу
Node.js/npm: Управління пакетами для компонентів JavaScript
Markdown: Весь контент уроків та документація

Архітектура:

Багатомовний освітній репозиторій з широкими перекладами
Структурований у модулі уроків (від 1-Introduction до 6-Data-Science-In-Wild)
Кожен урок включає README, ноутбуки, завдання та вікторини
Автономний додаток для вікторин на Vue.js для оцінювання до/після уроків
Підтримка GitHub Codespaces та контейнерів розробки VS Code

Команди налаштування

Налаштування репозиторію

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

Налаштування середовища Python

# 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

Налаштування додатка для вікторин

# 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

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

Налаштування проєктів візуалізації

Для проєктів візуалізації, таких як meaningful-visualizations (урок 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

Робочий процес розробки

Робота з Jupyter ноутбуками

Запустіть Jupyter у корені репозиторію:
```
jupyter notebook
```
Перейдіть до потрібної папки уроку
Відкрийте файли
```
.ipynb
```
, щоб виконувати вправи
Ноутбуки є самодостатніми з поясненнями та кодовими блоками
Більшість ноутбуків використовують pandas, numpy та matplotlib — переконайтеся, що вони встановлені

Структура уроку

Кожен урок зазвичай містить:

```
README.md
```
- Основний контент уроку з теорією та прикладами
```
notebook.ipynb
```
- Практичні вправи в Jupyter ноутбуках
```
assignment.ipynb
```
або
```
assignment.md
```
- Практичні завдання
Папка
```
solution/
```
- Ноутбуки з рішеннями та кодом
Папка
```
images/
```
- Додаткові візуальні матеріали

Розробка додатка для вікторин

Додаток на Vue.js 2 з функцією гарячого перезавантаження під час розробки
Вікторини зберігаються в
```
quiz-app/src/assets/translations/
```
Кожна мова має власну папку перекладів (en, fr, es тощо)
Нумерація вікторин починається з 0 і доходить до 39 (всього 40 вікторин)

Додавання перекладів

Переклади розміщуються в папці
```
translations/
```
у корені репозиторію
Кожна мова має повну структуру уроків, дзеркальну до англійської
Автоматичний переклад через GitHub Actions (co-op-translator.yml)

Інструкції з тестування

Тестування додатка для вікторин

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

Тестування ноутбуків

Автоматизованої системи тестування для ноутбуків немає
Ручна перевірка: Виконайте всі блоки коду послідовно, щоб переконатися у відсутності помилок
Перевірте доступність файлів даних та правильність вихідних результатів
Переконайтеся, що візуалізації відображаються правильно

Тестування документації

# Verify Docsify renders correctly
docsify serve

# Check for broken links manually by navigating through content
# Verify all lesson links work in the rendered documentation

Перевірка якості коду

# 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

Збірка та розгортання

Розгортання додатка для вікторин

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

Розгортання Azure Static Web Apps

Додаток quiz-app можна розгорнути на Azure Static Web Apps:

Створіть ресурс Azure Static Web App
Підключіть до репозиторію GitHub
Налаштуйте параметри збірки:
- Розташування додатка:
```
quiz-app
```
- Розташування вихідних даних:
```
dist
```
GitHub Actions автоматично розгорне при пуші

Сайт документації

# 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

Репозиторій включає конфігурацію контейнера розробки
Codespaces автоматично налаштовує середовище Python та Node.js
Відкрийте репозиторій у Codespace через інтерфейс GitHub
Усі залежності встановлюються автоматично

pandas: Обробка та аналіз даних
numpy: Числові обчислення
matplotlib: Візуалізація даних та побудова графіків
seaborn: Статистична візуалізація даних (деякі уроки)
scikit-learn: Машинне навчання (просунуті уроки)

Робота з файлами даних

Файли даних розташовані в папці
```
data/
```
або у папках, специфічних для уроків
Більшість ноутбуків очікують файли даних у відносних шляхах
Основний формат даних — CSV
Деякі уроки використовують JSON для прикладів нереляційних даних

Підтримка багатомовності

40+ мовних перекладів через автоматизовані GitHub Actions
Робочий процес перекладу в
```
.github/workflows/co-op-translator.yml
```
Переклади в папці
```
translations/
```
з кодами мов
Переклади вікторин у
```
quiz-app/src/assets/translations/
```

Варіанти середовища розробки

Локальна розробка: Встановіть Python, Jupyter, Node.js локально
GitHub Codespaces: Хмарне миттєве середовище розробки
VS Code Dev Containers: Локальна розробка на основі контейнерів
Binder: Запуск ноутбуків у хмарі (якщо налаштовано)

Вирішення поширених проблем

Проблеми з ядром Jupyter:

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

Помилки встановлення npm:

# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Помилки імпорту в ноутбуках:

Переконайтеся, що всі необхідні бібліотеки встановлені
Перевірте сумісність версії Python (рекомендується Python 3.7+)
Переконайтеся, що віртуальне середовище активоване

Docsify не завантажується:

Переконайтеся, що ви запускаєте сервер з кореня репозиторію
Перевірте наявність файлу
```
index.html
```
Переконайтеся у правильному доступі до мережі (порт 3000)

Міркування щодо продуктивності

Великі набори даних можуть займати час для завантаження в ноутбуках
Візуалізація може бути повільною для складних графіків
Сервер розробки Vue.js забезпечує гаряче перезавантаження для швидкої ітерації
Виробничі збірки оптимізовані та мінімізовані

Примітки щодо безпеки

Не слід зберігати конфіденційні дані або облікові дані в репозиторії
Використовуйте змінні середовища для будь-яких ключів API у хмарних уроках
Уроки, пов’язані з Azure, можуть вимагати облікових даних облікового запису Azure
Оновлюйте залежності для усунення вразливостей

Внесок у переклади

Автоматизовані переклади керуються через GitHub Actions
Вітаються ручні виправлення для точності перекладу
Дотримуйтесь існуючої структури папок перекладу
Оновлюйте посилання на вікторини, додаючи параметр мови:
```
?loc=fr
```
Тестуйте перекладені уроки на правильність відображення

Пов’язані ресурси

Основна навчальна програма: https://aka.ms/datascience-beginners
Microsoft Learn: https://docs.microsoft.com/learn/
Студентський центр: https://docs.microsoft.com/learn/student-hub
Форум обговорень: https://github.com/microsoft/Data-Science-For-Beginners/discussions
Інші навчальні програми Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners

Підтримка проєкту

Регулярні оновлення для актуалізації контенту
Вітаються внески від спільноти
Проблеми відстежуються на GitHub
PR перевіряються кураторами навчальної програми
Щомісячні огляди та оновлення контенту

Відмова від відповідальності:
Цей документ був перекладений за допомогою сервісу автоматичного перекладу Co-op Translator. Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ на його рідній мові слід вважати авторитетним джерелом. Для критичної інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникають внаслідок використання цього перекладу.