BethanyJep
7 months ago
committed by
GitHub
parent
4c6c18d70a
commit
c664b0f05d
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:02:42+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "ar"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## نظرة عامة على المشروع
|
||||
|
||||
"علم البيانات للمبتدئين" هو منهج شامل لمدة 10 أسابيع و20 درسًا تم إنشاؤه بواسطة Microsoft Azure Cloud Advocates. المستودع هو مورد تعليمي يشرح مفاهيم علم البيانات الأساسية من خلال دروس قائمة على المشاريع، بما في ذلك دفاتر Jupyter، اختبارات تفاعلية، وتكليفات عملية.
|
||||
|
||||
**التقنيات الرئيسية:**
|
||||
- **دفاتر Jupyter**: الوسيلة التعليمية الأساسية باستخدام 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
|
||||
|
||||
## أوامر الإعداد
|
||||
|
||||
### إعداد المستودع
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### إعداد بيئة Python
|
||||
```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
|
||||
```
|
||||
|
||||
### إعداد تطبيق الاختبارات
|
||||
```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
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### إعداد مشاريع التصوير
|
||||
بالنسبة لمشاريع التصوير مثل meaningful-visualizations (الدرس 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
|
||||
```
|
||||
|
||||
|
||||
## سير العمل التطويري
|
||||
|
||||
### العمل مع دفاتر Jupyter
|
||||
1. تشغيل Jupyter في جذر المستودع: `jupyter notebook`
|
||||
2. الانتقال إلى مجلد الدرس المطلوب
|
||||
3. فتح ملفات `.ipynb` للعمل على التمارين
|
||||
4. الدفاتر مكتفية ذاتيًا مع شروحات وخلايا أكواد
|
||||
5. معظم الدفاتر تستخدم 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)
|
||||
|
||||
## تعليمات الاختبار
|
||||
|
||||
### اختبار تطبيق الاختبارات
|
||||
```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
|
||||
```
|
||||
|
||||
### اختبار الدفاتر
|
||||
- لا يوجد إطار اختبار تلقائي للدفاتر
|
||||
- التحقق اليدوي: تشغيل جميع الخلايا بالتسلسل للتأكد من عدم وجود أخطاء
|
||||
- التحقق من الوصول إلى ملفات البيانات وتوليد المخرجات بشكل صحيح
|
||||
- التأكد من عرض التصورات بشكل صحيح
|
||||
|
||||
### اختبار التوثيق
|
||||
```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
|
||||
```
|
||||
|
||||
### فحوصات جودة الأكواد
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## إرشادات نمط الأكواد
|
||||
|
||||
### Python (دفاتر Jupyter)
|
||||
- اتباع إرشادات نمط PEP 8 لأكواد Python
|
||||
- استخدام أسماء متغيرات واضحة تشرح البيانات التي يتم تحليلها
|
||||
- تضمين خلايا Markdown مع شروحات قبل خلايا الأكواد
|
||||
- التركيز على مفاهيم أو عمليات محددة في خلايا الأكواد
|
||||
- استخدام pandas لمعالجة البيانات، matplotlib للتصور
|
||||
- نمط الاستيراد الشائع:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- اتباع دليل نمط Vue.js 2 وأفضل الممارسات
|
||||
- تكوين ESLint في `quiz-app/package.json`
|
||||
- استخدام مكونات Vue ذات الملف الواحد (.vue files)
|
||||
- الحفاظ على هيكلية قائمة على المكونات
|
||||
- تشغيل `npm run lint` قبل تقديم التغييرات
|
||||
|
||||
### توثيق Markdown
|
||||
- استخدام تسلسل واضح للعناوين (# ## ### إلخ)
|
||||
- تضمين كتل الأكواد مع محددات اللغة
|
||||
- إضافة نصوص بديلة للصور
|
||||
- الربط بالدروس والموارد ذات الصلة
|
||||
- الحفاظ على طول السطور معقولًا لسهولة القراءة
|
||||
|
||||
### تنظيم الملفات
|
||||
- محتوى الدروس في مجلدات مرقمة (01-defining-data-science، إلخ)
|
||||
- الحلول في مجلدات فرعية مخصصة `solution/`
|
||||
- الترجمات تعكس الهيكلية الإنجليزية في مجلد `translations/`
|
||||
- الاحتفاظ بملفات البيانات في `data/` أو مجلدات خاصة بالدروس
|
||||
|
||||
## البناء والنشر
|
||||
|
||||
### نشر تطبيق الاختبارات
|
||||
```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.)
|
||||
```
|
||||
|
||||
### نشر تطبيقات Azure Static Web
|
||||
يمكن نشر quiz-app على Azure Static Web Apps:
|
||||
1. إنشاء مورد Azure Static Web App
|
||||
2. الاتصال بمستودع GitHub
|
||||
3. تكوين إعدادات البناء:
|
||||
- موقع التطبيق: `quiz-app`
|
||||
- موقع الإخراج: `dist`
|
||||
4. سير عمل GitHub Actions سيقوم بالنشر تلقائيًا عند الدفع
|
||||
|
||||
### موقع التوثيق
|
||||
```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
|
||||
- المستودع يتضمن تكوين حاوية التطوير
|
||||
- Codespaces يقوم تلقائيًا بإعداد بيئة Python وNode.js
|
||||
- فتح المستودع في Codespace عبر واجهة GitHub
|
||||
- تثبيت جميع التبعيات تلقائيًا
|
||||
|
||||
## إرشادات طلبات السحب
|
||||
|
||||
### قبل التقديم
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### تنسيق عنوان طلب السحب
|
||||
- استخدام عناوين واضحة وواصفة
|
||||
- التنسيق: `[المكون] وصف مختصر`
|
||||
- أمثلة:
|
||||
- `[Lesson 7] إصلاح خطأ استيراد في دفتر Python`
|
||||
- `[Quiz App] إضافة ترجمة ألمانية`
|
||||
- `[Docs] تحديث README بمتطلبات جديدة`
|
||||
|
||||
### الفحوصات المطلوبة
|
||||
- التأكد من تشغيل جميع الأكواد دون أخطاء
|
||||
- التحقق من تنفيذ الدفاتر بالكامل
|
||||
- التأكد من بناء تطبيقات Vue.js بنجاح
|
||||
- التحقق من عمل روابط التوثيق
|
||||
- اختبار تطبيق الاختبارات إذا تم تعديله
|
||||
- التحقق من الحفاظ على هيكلية الترجمات
|
||||
|
||||
### إرشادات المساهمة
|
||||
- اتباع نمط الأكواد والأنماط الموجودة
|
||||
- إضافة تعليقات تفسيرية للمنطق المعقد
|
||||
- تحديث التوثيق ذي الصلة
|
||||
- اختبار التغييرات عبر وحدات الدروس المختلفة إذا كان ذلك ممكنًا
|
||||
- مراجعة ملف CONTRIBUTING.md
|
||||
|
||||
## ملاحظات إضافية
|
||||
|
||||
### المكتبات الشائعة الاستخدام
|
||||
- **pandas**: معالجة وتحليل البيانات
|
||||
- **numpy**: الحوسبة العددية
|
||||
- **matplotlib**: التصور ورسم البيانات
|
||||
- **seaborn**: التصور الإحصائي للبيانات (بعض الدروس)
|
||||
- **scikit-learn**: التعلم الآلي (الدروس المتقدمة)
|
||||
|
||||
### العمل مع ملفات البيانات
|
||||
- ملفات البيانات موجودة في مجلد `data/` أو مجلدات خاصة بالدروس
|
||||
- معظم الدفاتر تتوقع ملفات البيانات في مسارات نسبية
|
||||
- ملفات CSV هي تنسيق البيانات الأساسي
|
||||
- بعض الدروس تستخدم JSON لأمثلة البيانات غير العلائقية
|
||||
|
||||
### دعم متعدد اللغات
|
||||
- أكثر من 40 ترجمة لغوية عبر GitHub Actions تلقائيًا
|
||||
- سير عمل الترجمة في `.github/workflows/co-op-translator.yml`
|
||||
- الترجمات في مجلد `translations/` مع رموز اللغات
|
||||
- ترجمات الاختبارات في `quiz-app/src/assets/translations/`
|
||||
|
||||
### خيارات بيئة التطوير
|
||||
1. **التطوير المحلي**: تثبيت Python، Jupyter، Node.js محليًا
|
||||
2. **GitHub Codespaces**: بيئة تطوير سحابية فورية
|
||||
3. **VS Code Dev Containers**: تطوير محلي قائم على الحاويات
|
||||
4. **Binder**: تشغيل الدفاتر في السحابة (إذا تم تكوينه)
|
||||
|
||||
### إرشادات محتوى الدروس
|
||||
- كل درس مكتفٍ ذاتيًا ولكنه يبني على المفاهيم السابقة
|
||||
- اختبارات ما قبل الدرس تختبر المعرفة السابقة
|
||||
- اختبارات ما بعد الدرس تعزز التعلم
|
||||
- التكليفات توفر ممارسة عملية
|
||||
- الرسومات التخطيطية تقدم ملخصات بصرية
|
||||
|
||||
### استكشاف المشكلات الشائعة
|
||||
|
||||
**مشكلات Kernel في Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**فشل تثبيت npm:**
|
||||
```bash
|
||||
# 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 للمبتدئين، AI للمبتدئين، تطوير الويب للمبتدئين
|
||||
|
||||
## صيانة المشروع
|
||||
- تحديثات منتظمة للحفاظ على المحتوى محدثًا
|
||||
- مساهمات المجتمع مرحب بها
|
||||
- تتبع المشكلات على GitHub
|
||||
- مراجعة طلبات السحب بواسطة مشرفي المنهج
|
||||
- مراجعات وتحديثات شهرية للمحتوى
|
||||
|
||||
---
|
||||
|
||||
**إخلاء المسؤولية**:
|
||||
تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية هو المصدر الموثوق. للحصول على معلومات حساسة، يُوصى بالاستعانة بترجمة بشرية احترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:16:58+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "br"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Visão Geral do Projeto
|
||||
|
||||
Data Science for Beginners é um currículo abrangente de 10 semanas e 20 lições criado pelos Advocates de Nuvem da Microsoft Azure. O repositório é um recurso de aprendizado que ensina conceitos fundamentais de ciência de dados por meio de lições baseadas em projetos, incluindo notebooks Jupyter, quizzes interativos e tarefas práticas.
|
||||
|
||||
**Principais Tecnologias:**
|
||||
- **Jupyter Notebooks**: Meio principal de aprendizado usando Python 3
|
||||
- **Bibliotecas Python**: pandas, numpy, matplotlib para análise e visualização de dados
|
||||
- **Vue.js 2**: Aplicativo de quiz (pasta quiz-app)
|
||||
- **Docsify**: Gerador de site de documentação para acesso offline
|
||||
- **Node.js/npm**: Gerenciamento de pacotes para componentes JavaScript
|
||||
- **Markdown**: Todo o conteúdo das lições e documentação
|
||||
|
||||
**Arquitetura:**
|
||||
- Repositório educacional multilíngue com extensas traduções
|
||||
- Estruturado em módulos de lições (1-Introdução até 6-Ciência-de-Dados-na-Prática)
|
||||
- Cada lição inclui README, notebooks, tarefas e quizzes
|
||||
- Aplicativo de quiz Vue.js independente para avaliações pré/pós-lição
|
||||
- Suporte para GitHub Codespaces e contêineres de desenvolvimento do VS Code
|
||||
|
||||
## Comandos de Configuração
|
||||
|
||||
### Configuração do Repositório
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Configuração do Ambiente Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Configuração do Aplicativo de Quiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Servidor de Documentação Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Configuração de Projetos de Visualização
|
||||
Para projetos de visualização como meaningful-visualizations (lição 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
|
||||
```
|
||||
|
||||
|
||||
## Fluxo de Trabalho de Desenvolvimento
|
||||
|
||||
### Trabalhando com Jupyter Notebooks
|
||||
1. Inicie o Jupyter na raiz do repositório: `jupyter notebook`
|
||||
2. Navegue até a pasta da lição desejada
|
||||
3. Abra os arquivos `.ipynb` para realizar os exercícios
|
||||
4. Os notebooks são autossuficientes, com explicações e células de código
|
||||
5. A maioria dos notebooks utiliza pandas, numpy e matplotlib - certifique-se de que estão instalados
|
||||
|
||||
### Estrutura das Lições
|
||||
Cada lição geralmente contém:
|
||||
- `README.md` - Conteúdo principal da lição com teoria e exemplos
|
||||
- `notebook.ipynb` - Exercícios práticos no Jupyter Notebook
|
||||
- `assignment.ipynb` ou `assignment.md` - Tarefas práticas
|
||||
- Pasta `solution/` - Notebooks e códigos de solução
|
||||
- Pasta `images/` - Materiais visuais de suporte
|
||||
|
||||
### Desenvolvimento do Aplicativo de Quiz
|
||||
- Aplicativo Vue.js 2 com recarregamento automático durante o desenvolvimento
|
||||
- Quizzes armazenados em `quiz-app/src/assets/translations/`
|
||||
- Cada idioma tem sua própria pasta de tradução (en, fr, es, etc.)
|
||||
- A numeração dos quizzes começa em 0 e vai até 39 (40 quizzes no total)
|
||||
|
||||
### Adicionando Traduções
|
||||
- Traduções vão na pasta `translations/` na raiz do repositório
|
||||
- Cada idioma tem a estrutura completa das lições espelhada do inglês
|
||||
- Tradução automatizada via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instruções de Teste
|
||||
|
||||
### Teste do Aplicativo de Quiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Teste de Notebooks
|
||||
- Não existe um framework de teste automatizado para notebooks
|
||||
- Validação manual: Execute todas as células em sequência para garantir que não há erros
|
||||
- Verifique se os arquivos de dados estão acessíveis e os resultados são gerados corretamente
|
||||
- Certifique-se de que as visualizações são renderizadas corretamente
|
||||
|
||||
### Teste de Documentação
|
||||
```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
|
||||
```
|
||||
|
||||
### Verificações de Qualidade de Código
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Diretrizes de Estilo de Código
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Siga as diretrizes de estilo PEP 8 para código Python
|
||||
- Use nomes de variáveis claros que expliquem os dados sendo analisados
|
||||
- Inclua células markdown com explicações antes das células de código
|
||||
- Mantenha as células de código focadas em conceitos ou operações únicas
|
||||
- Use pandas para manipulação de dados, matplotlib para visualização
|
||||
- Padrão comum de importação:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Siga o guia de estilo e as melhores práticas do Vue.js 2
|
||||
- Configuração do ESLint em `quiz-app/package.json`
|
||||
- Use componentes Vue de arquivo único (.vue files)
|
||||
- Mantenha uma arquitetura baseada em componentes
|
||||
- Execute `npm run lint` antes de enviar alterações
|
||||
|
||||
### Documentação Markdown
|
||||
- Use uma hierarquia clara de cabeçalhos (# ## ### etc.)
|
||||
- Inclua blocos de código com especificadores de linguagem
|
||||
- Adicione texto alternativo para imagens
|
||||
- Link para lições e recursos relacionados
|
||||
- Mantenha os comprimentos das linhas razoáveis para facilitar a leitura
|
||||
|
||||
### Organização de Arquivos
|
||||
- Conteúdo das lições em pastas numeradas (01-defining-data-science, etc.)
|
||||
- Soluções em subpastas dedicadas `solution/`
|
||||
- Traduções espelham a estrutura em inglês na pasta `translations/`
|
||||
- Mantenha os arquivos de dados na pasta `data/` ou em pastas específicas de lições
|
||||
|
||||
## Construção e Implantação
|
||||
|
||||
### Implantação do Aplicativo de Quiz
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Implantação em Azure Static Web Apps
|
||||
O quiz-app pode ser implantado no Azure Static Web Apps:
|
||||
1. Crie um recurso Azure Static Web App
|
||||
2. Conecte ao repositório GitHub
|
||||
3. Configure as configurações de build:
|
||||
- Localização do aplicativo: `quiz-app`
|
||||
- Localização de saída: `dist`
|
||||
4. O workflow do GitHub Actions fará a implantação automática ao enviar alterações
|
||||
|
||||
### Site de Documentação
|
||||
```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
|
||||
- O repositório inclui configuração de contêiner de desenvolvimento
|
||||
- Codespaces configura automaticamente o ambiente Python e Node.js
|
||||
- Abra o repositório no Codespace via interface do GitHub
|
||||
- Todas as dependências são instaladas automaticamente
|
||||
|
||||
## Diretrizes para Pull Requests
|
||||
|
||||
### Antes de Enviar
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Formato do Título do PR
|
||||
- Use títulos claros e descritivos
|
||||
- Formato: `[Componente] Breve descrição`
|
||||
- Exemplos:
|
||||
- `[Lição 7] Corrigir erro de importação no notebook Python`
|
||||
- `[Aplicativo de Quiz] Adicionar tradução em alemão`
|
||||
- `[Docs] Atualizar README com novos pré-requisitos`
|
||||
|
||||
### Verificações Necessárias
|
||||
- Certifique-se de que todo o código funciona sem erros
|
||||
- Verifique se os notebooks executam completamente
|
||||
- Confirme que os aplicativos Vue.js são construídos com sucesso
|
||||
- Verifique se os links da documentação funcionam
|
||||
- Teste o aplicativo de quiz se modificado
|
||||
- Confirme que as traduções mantêm uma estrutura consistente
|
||||
|
||||
### Diretrizes de Contribuição
|
||||
- Siga o estilo e os padrões de código existentes
|
||||
- Adicione comentários explicativos para lógica complexa
|
||||
- Atualize a documentação relevante
|
||||
- Teste alterações em diferentes módulos de lições, se aplicável
|
||||
- Revise o arquivo CONTRIBUTING.md
|
||||
|
||||
## Notas Adicionais
|
||||
|
||||
### Bibliotecas Comuns Utilizadas
|
||||
- **pandas**: Manipulação e análise de dados
|
||||
- **numpy**: Computação numérica
|
||||
- **matplotlib**: Visualização e plotagem de dados
|
||||
- **seaborn**: Visualização estatística de dados (algumas lições)
|
||||
- **scikit-learn**: Aprendizado de máquina (lições avançadas)
|
||||
|
||||
### Trabalhando com Arquivos de Dados
|
||||
- Arquivos de dados localizados na pasta `data/` ou em diretórios específicos de lições
|
||||
- A maioria dos notebooks espera arquivos de dados em caminhos relativos
|
||||
- Arquivos CSV são o formato de dados principal
|
||||
- Algumas lições utilizam JSON para exemplos de dados não relacionais
|
||||
|
||||
### Suporte Multilíngue
|
||||
- Mais de 40 traduções de idiomas via GitHub Actions automatizado
|
||||
- Workflow de tradução em `.github/workflows/co-op-translator.yml`
|
||||
- Traduções na pasta `translations/` com códigos de idioma
|
||||
- Traduções de quizzes em `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opções de Ambiente de Desenvolvimento
|
||||
1. **Desenvolvimento Local**: Instale Python, Jupyter, Node.js localmente
|
||||
2. **GitHub Codespaces**: Ambiente de desenvolvimento instantâneo baseado em nuvem
|
||||
3. **Contêineres de Desenvolvimento do VS Code**: Desenvolvimento local baseado em contêiner
|
||||
4. **Binder**: Inicie notebooks na nuvem (se configurado)
|
||||
|
||||
### Diretrizes de Conteúdo das Lições
|
||||
- Cada lição é independente, mas constrói conceitos anteriores
|
||||
- Quizzes pré-lição testam conhecimento prévio
|
||||
- Quizzes pós-lição reforçam o aprendizado
|
||||
- Tarefas fornecem prática prática
|
||||
- Sketchnotes fornecem resumos visuais
|
||||
|
||||
### Solução de Problemas Comuns
|
||||
|
||||
**Problemas com Kernel do Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Falhas na Instalação do npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Erros de Importação em Notebooks:**
|
||||
- Verifique se todas as bibliotecas necessárias estão instaladas
|
||||
- Confira a compatibilidade da versão do Python (recomendado Python 3.7+)
|
||||
- Certifique-se de que o ambiente virtual está ativado
|
||||
|
||||
**Docsify Não Carregando:**
|
||||
- Verifique se você está servindo a partir da raiz do repositório
|
||||
- Confira se o arquivo `index.html` existe
|
||||
- Certifique-se de que há acesso adequado à rede (porta 3000)
|
||||
|
||||
### Considerações de Desempenho
|
||||
- Conjuntos de dados grandes podem levar tempo para carregar nos notebooks
|
||||
- A renderização de visualizações pode ser lenta para gráficos complexos
|
||||
- O servidor de desenvolvimento Vue.js permite recarregamento rápido para iteração rápida
|
||||
- Builds de produção são otimizados e minificados
|
||||
|
||||
### Notas de Segurança
|
||||
- Nenhum dado sensível ou credenciais deve ser enviado
|
||||
- Use variáveis de ambiente para quaisquer chaves de API em lições na nuvem
|
||||
- Lições relacionadas ao Azure podem exigir credenciais de conta Azure
|
||||
- Mantenha as dependências atualizadas para patches de segurança
|
||||
|
||||
## Contribuindo com Traduções
|
||||
- Traduções automatizadas gerenciadas via GitHub Actions
|
||||
- Correções manuais são bem-vindas para precisão das traduções
|
||||
- Siga a estrutura de pastas de tradução existente
|
||||
- Atualize os links dos quizzes para incluir o parâmetro de idioma: `?loc=fr`
|
||||
- Teste as lições traduzidas para garantir a renderização adequada
|
||||
|
||||
## Recursos Relacionados
|
||||
- Currículo principal: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Fórum de Discussão: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Outros currículos da Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Manutenção do Projeto
|
||||
- Atualizações regulares para manter o conteúdo atual
|
||||
- Contribuições da comunidade são bem-vindas
|
||||
- Problemas rastreados no GitHub
|
||||
- PRs revisados pelos mantenedores do currículo
|
||||
- Revisões e atualizações de conteúdo mensais
|
||||
|
||||
---
|
||||
|
||||
**Aviso Legal**:
|
||||
Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:36:41+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "cs"
|
||||
}
|
||||
-->
|
||||
# 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.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:25:00+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "da"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Projektoversigt
|
||||
|
||||
Data Science for Beginners er et omfattende 10-ugers, 20-lektions pensum skabt af Microsoft Azure Cloud Advocates. Repositoriet er en læringsressource, der underviser i grundlæggende data science-koncepter gennem projektbaserede lektioner, herunder Jupyter-notebooks, interaktive quizzer og praktiske opgaver.
|
||||
|
||||
**Nøgleteknologier:**
|
||||
- **Jupyter Notebooks**: Primært læringsmedium ved brug af Python 3
|
||||
- **Python-biblioteker**: pandas, numpy, matplotlib til dataanalyse og visualisering
|
||||
- **Vue.js 2**: Quiz-applikation (quiz-app-mappe)
|
||||
- **Docsify**: Dokumentationsgenerator til offline adgang
|
||||
- **Node.js/npm**: Pakkehåndtering til JavaScript-komponenter
|
||||
- **Markdown**: Alt lektionsindhold og dokumentation
|
||||
|
||||
**Arkitektur:**
|
||||
- Flersproget uddannelsesrepository med omfattende oversættelser
|
||||
- Struktureret i lektionsmoduler (1-Introduction til 6-Data-Science-In-Wild)
|
||||
- Hver lektion inkluderer README, notebooks, opgaver og quizzer
|
||||
- Selvstændig Vue.js quiz-applikation til før/efter-lektionsvurderinger
|
||||
- GitHub Codespaces og VS Code dev-containere understøttes
|
||||
|
||||
## Opsætningskommandoer
|
||||
|
||||
### Repository-opsætning
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Opsætning af Python-miljø
|
||||
```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
|
||||
```
|
||||
|
||||
### Opsætning af quiz-applikation
|
||||
```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-dokumentationsserver
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Opsætning af visualiseringsprojekter
|
||||
For visualiseringsprojekter som meaningful-visualizations (lektion 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
|
||||
```
|
||||
|
||||
|
||||
## Udviklingsarbejdsgang
|
||||
|
||||
### Arbejde med Jupyter-notebooks
|
||||
1. Start Jupyter i repositoryets rod: `jupyter notebook`
|
||||
2. Naviger til den ønskede lektionsmappe
|
||||
3. Åbn `.ipynb`-filer for at arbejde med øvelserne
|
||||
4. Notebooks er selvstændige med forklaringer og kodeceller
|
||||
5. De fleste notebooks bruger pandas, numpy og matplotlib - sørg for, at disse er installeret
|
||||
|
||||
### Lektionsstruktur
|
||||
Hver lektion indeholder typisk:
|
||||
- `README.md` - Hovedindhold med teori og eksempler
|
||||
- `notebook.ipynb` - Praktiske Jupyter-notebook-øvelser
|
||||
- `assignment.ipynb` eller `assignment.md` - Øvelsesopgaver
|
||||
- `solution/`-mappe - Løsningsnotebooks og kode
|
||||
- `images/`-mappe - Understøttende visuelle materialer
|
||||
|
||||
### Udvikling af quiz-applikation
|
||||
- Vue.js 2-applikation med hot-reload under udvikling
|
||||
- Quizzer gemmes i `quiz-app/src/assets/translations/`
|
||||
- Hvert sprog har sin egen oversættelsesmappe (en, fr, es osv.)
|
||||
- Quiznummerering starter ved 0 og går op til 39 (i alt 40 quizzer)
|
||||
|
||||
### Tilføjelse af oversættelser
|
||||
- Oversættelser placeres i `translations/`-mappen i repositoryets rod
|
||||
- Hvert sprog har en komplet lektionsstruktur, der spejler engelsk
|
||||
- Automatiseret oversættelse via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Testinstruktioner
|
||||
|
||||
### Test af quiz-applikation
|
||||
```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
|
||||
```
|
||||
|
||||
### Test af notebooks
|
||||
- Der findes ikke noget automatiseret testframework til notebooks
|
||||
- Manuel validering: Kør alle celler i rækkefølge for at sikre, at der ikke er fejl
|
||||
- Verificer, at datafiler er tilgængelige, og at output genereres korrekt
|
||||
- Kontroller, at visualiseringer gengives korrekt
|
||||
|
||||
### Test af dokumentation
|
||||
```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
|
||||
```
|
||||
|
||||
### Kvalitetskontrol af kode
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Retningslinjer for kodestil
|
||||
|
||||
### Python (Jupyter-notebooks)
|
||||
- Følg PEP 8-stilretningslinjer for Python-kode
|
||||
- Brug klare variabelnavne, der forklarer de analyserede data
|
||||
- Inkluder markdown-celler med forklaringer før kodeceller
|
||||
- Hold kodeceller fokuseret på enkeltstående koncepter eller operationer
|
||||
- Brug pandas til datamanipulation, matplotlib til visualisering
|
||||
- Almindeligt importmønster:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Følg Vue.js 2-stilguide og bedste praksis
|
||||
- ESLint-konfiguration i `quiz-app/package.json`
|
||||
- Brug Vue single-file-komponenter (.vue-filer)
|
||||
- Bevar komponentbaseret arkitektur
|
||||
- Kør `npm run lint` før ændringer committes
|
||||
|
||||
### Markdown-dokumentation
|
||||
- Brug en klar overskriftsstruktur (# ## ### osv.)
|
||||
- Inkluder kodeblokke med sprogangivelser
|
||||
- Tilføj alt-tekst til billeder
|
||||
- Link til relaterede lektioner og ressourcer
|
||||
- Hold linjelængder rimelige for læsbarhed
|
||||
|
||||
### Filorganisering
|
||||
- Lektionsindhold i nummererede mapper (01-defining-data-science osv.)
|
||||
- Løsninger i dedikerede `solution/`-undermapper
|
||||
- Oversættelser spejler engelsk struktur i `translations/`-mappen
|
||||
- Opbevar datafiler i `data/` eller lektionsspecifikke mapper
|
||||
|
||||
## Bygning og udrulning
|
||||
|
||||
### Udrulning af quiz-applikation
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Udrulning til Azure Static Web Apps
|
||||
Quiz-applikationen kan udrulles til Azure Static Web Apps:
|
||||
1. Opret en Azure Static Web App-ressource
|
||||
2. Forbind til GitHub-repositoriet
|
||||
3. Konfigurer build-indstillinger:
|
||||
- App-placering: `quiz-app`
|
||||
- Output-placering: `dist`
|
||||
4. GitHub Actions workflow udruller automatisk ved push
|
||||
|
||||
### Dokumentationsside
|
||||
```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
|
||||
- Repositoriet inkluderer dev-container-konfiguration
|
||||
- Codespaces opsætter automatisk Python- og Node.js-miljø
|
||||
- Åbn repositoriet i Codespace via GitHub UI
|
||||
- Alle afhængigheder installeres automatisk
|
||||
|
||||
## Retningslinjer for pull requests
|
||||
|
||||
### Før indsendelse
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR-titelformat
|
||||
- Brug klare, beskrivende titler
|
||||
- Format: `[Komponent] Kort beskrivelse`
|
||||
- Eksempler:
|
||||
- `[Lektion 7] Ret Python-notebook-importfejl`
|
||||
- `[Quiz App] Tilføj tysk oversættelse`
|
||||
- `[Docs] Opdater README med nye forudsætninger`
|
||||
|
||||
### Påkrævede kontroller
|
||||
- Sørg for, at al kode kører uden fejl
|
||||
- Verificer, at notebooks udføres fuldstændigt
|
||||
- Bekræft, at Vue.js-applikationer bygger korrekt
|
||||
- Kontroller, at dokumentationslinks fungerer
|
||||
- Test quiz-applikationen, hvis den er ændret
|
||||
- Verificer, at oversættelser bevarer en ensartet struktur
|
||||
|
||||
### Retningslinjer for bidrag
|
||||
- Følg eksisterende kodestil og mønstre
|
||||
- Tilføj forklarende kommentarer til kompleks logik
|
||||
- Opdater relevant dokumentation
|
||||
- Test ændringer på tværs af forskellige lektionsmoduler, hvis det er relevant
|
||||
- Gennemgå CONTRIBUTING.md-filen
|
||||
|
||||
## Yderligere noter
|
||||
|
||||
### Almindeligt anvendte biblioteker
|
||||
- **pandas**: Datamanipulation og analyse
|
||||
- **numpy**: Numerisk beregning
|
||||
- **matplotlib**: Datavisualisering og diagrammer
|
||||
- **seaborn**: Statistisk datavisualisering (nogle lektioner)
|
||||
- **scikit-learn**: Maskinlæring (avancerede lektioner)
|
||||
|
||||
### Arbejde med datafiler
|
||||
- Datafiler findes i `data/`-mappen eller lektionsspecifikke mapper
|
||||
- De fleste notebooks forventer datafiler i relative stier
|
||||
- CSV-filer er det primære dataformat
|
||||
- Nogle lektioner bruger JSON til eksempler på ikke-relationelle data
|
||||
|
||||
### Flersproget understøttelse
|
||||
- 40+ sprogoversættelser via automatiserede GitHub Actions
|
||||
- Oversættelsesworkflow i `.github/workflows/co-op-translator.yml`
|
||||
- Oversættelser i `translations/`-mappen med sprogkoder
|
||||
- Quiz-oversættelser i `quiz-app/src/assets/translations/`
|
||||
|
||||
### Udviklingsmiljømuligheder
|
||||
1. **Lokal udvikling**: Installer Python, Jupyter, Node.js lokalt
|
||||
2. **GitHub Codespaces**: Cloud-baseret øjeblikkeligt udviklingsmiljø
|
||||
3. **VS Code Dev-containere**: Lokalt containerbaseret udvikling
|
||||
4. **Binder**: Start notebooks i skyen (hvis konfigureret)
|
||||
|
||||
### Retningslinjer for lektionsindhold
|
||||
- Hver lektion er selvstændig, men bygger på tidligere koncepter
|
||||
- Quizzer før lektionen tester forudgående viden
|
||||
- Quizzer efter lektionen styrker læringen
|
||||
- Opgaver giver praktisk erfaring
|
||||
- Sketchnotes giver visuelle opsummeringer
|
||||
|
||||
### Fejlfinding af almindelige problemer
|
||||
|
||||
**Problemer med Jupyter-kernel:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm-installationsfejl:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Importfejl i notebooks:**
|
||||
- Verificer, at alle nødvendige biblioteker er installeret
|
||||
- Kontroller Python-versionens kompatibilitet (Python 3.7+ anbefales)
|
||||
- Sørg for, at det virtuelle miljø er aktiveret
|
||||
|
||||
**Docsify indlæses ikke:**
|
||||
- Verificer, at du serverer fra repositoryets rod
|
||||
- Kontroller, at `index.html` findes
|
||||
- Sørg for korrekt netværksadgang (port 3000)
|
||||
|
||||
### Ydelseshensyn
|
||||
- Store datasæt kan tage tid at indlæse i notebooks
|
||||
- Visualiseringer kan være langsomme at gengive for komplekse diagrammer
|
||||
- Vue.js dev-server muliggør hot-reload for hurtig iteration
|
||||
- Produktionsbuilds er optimerede og minimerede
|
||||
|
||||
### Sikkerhedsnoter
|
||||
- Ingen følsomme data eller legitimationsoplysninger bør committes
|
||||
- Brug miljøvariabler til eventuelle API-nøgler i cloud-lektioner
|
||||
- Azure-relaterede lektioner kan kræve Azure-kontooplysninger
|
||||
- Hold afhængigheder opdaterede for sikkerhedsrettelser
|
||||
|
||||
## Bidrag til oversættelser
|
||||
- Automatiserede oversættelser håndteres via GitHub Actions
|
||||
- Manuelle rettelser er velkomne for at sikre oversættelseskvalitet
|
||||
- Følg eksisterende oversættelsesmappe-struktur
|
||||
- Opdater quiz-links til at inkludere sprogparameter: `?loc=fr`
|
||||
- Test oversatte lektioner for korrekt gengivelse
|
||||
|
||||
## Relaterede ressourcer
|
||||
- Hovedpensum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Diskussionsforum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Andre Microsoft-pensum: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Projektvedligeholdelse
|
||||
- Regelmæssige opdateringer for at holde indholdet aktuelt
|
||||
- Bidrag fra fællesskabet er velkomne
|
||||
- Issues spores på GitHub
|
||||
- PR'er gennemgås af pensumvedligeholdere
|
||||
- Månedlige indholdsrevisioner og opdateringer
|
||||
|
||||
---
|
||||
|
||||
**Ansvarsfraskrivelse**:
|
||||
Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal det bemærkes, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der måtte opstå som følge af brugen af denne oversættelse.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T10:57:35+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "en"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Project Overview
|
||||
|
||||
Data Science for Beginners is a comprehensive 10-week, 20-lesson curriculum developed by Microsoft Azure Cloud Advocates. This repository serves as a learning resource to teach foundational data science concepts through project-based lessons, including Jupyter notebooks, interactive quizzes, and hands-on assignments.
|
||||
|
||||
**Key Technologies:**
|
||||
- **Jupyter Notebooks**: Primary learning tool using Python 3
|
||||
- **Python Libraries**: pandas, numpy, matplotlib for data analysis and visualization
|
||||
- **Vue.js 2**: Quiz application (located in the quiz-app folder)
|
||||
- **Docsify**: Documentation site generator for offline access
|
||||
- **Node.js/npm**: Package management for JavaScript components
|
||||
- **Markdown**: All lesson content and documentation
|
||||
|
||||
**Architecture:**
|
||||
- Multi-language educational repository with extensive translations
|
||||
- Organized into lesson modules (1-Introduction through 6-Data-Science-In-Wild)
|
||||
- Each lesson includes README files, notebooks, assignments, and quizzes
|
||||
- Standalone Vue.js quiz application for pre/post-lesson assessments
|
||||
- GitHub Codespaces and VS Code dev containers supported
|
||||
|
||||
## Setup Commands
|
||||
|
||||
### Repository Setup
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python Environment Setup
|
||||
```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
|
||||
```
|
||||
|
||||
### Quiz Application Setup
|
||||
```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 Documentation Server
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Visualization Projects Setup
|
||||
For visualization projects like meaningful-visualizations (lesson 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
|
||||
```
|
||||
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Working with Jupyter Notebooks
|
||||
1. Start Jupyter in the repository root: `jupyter notebook`
|
||||
2. Navigate to the desired lesson folder
|
||||
3. Open `.ipynb` files to work through exercises
|
||||
4. Notebooks are self-contained with explanations and code cells
|
||||
5. Most notebooks use pandas, numpy, and matplotlib - ensure these libraries are installed
|
||||
|
||||
### Lesson Structure
|
||||
Each lesson typically includes:
|
||||
- `README.md` - Main lesson content with theory and examples
|
||||
- `notebook.ipynb` - Hands-on Jupyter notebook exercises
|
||||
- `assignment.ipynb` or `assignment.md` - Practice assignments
|
||||
- `solution/` folder - Solution notebooks and code
|
||||
- `images/` folder - Supporting visual materials
|
||||
|
||||
### Quiz Application Development
|
||||
- Vue.js 2 application with hot-reload during development
|
||||
- Quizzes stored in `quiz-app/src/assets/translations/`
|
||||
- Each language has its own translation folder (en, fr, es, etc.)
|
||||
- Quiz numbering starts at 0 and goes up to 39 (40 quizzes total)
|
||||
|
||||
### Adding Translations
|
||||
- Translations are stored in the `translations/` folder at the repository root
|
||||
- Each language mirrors the complete lesson structure from English
|
||||
- Automated translation via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Testing Instructions
|
||||
|
||||
### Quiz Application Testing
|
||||
```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
|
||||
```
|
||||
|
||||
### Notebook Testing
|
||||
- No automated test framework exists for notebooks
|
||||
- Manual validation: Run all cells in sequence to ensure no errors
|
||||
- Verify data files are accessible and outputs are generated correctly
|
||||
- Check that visualizations render properly
|
||||
|
||||
### Documentation Testing
|
||||
```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
|
||||
```
|
||||
|
||||
### Code Quality Checks
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Follow PEP 8 style guidelines for Python code
|
||||
- Use clear variable names that describe the data being analyzed
|
||||
- Include markdown cells with explanations before code cells
|
||||
- Keep code cells focused on single concepts or operations
|
||||
- Use pandas for data manipulation, matplotlib for visualization
|
||||
- Common import pattern:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Follow Vue.js 2 style guide and best practices
|
||||
- ESLint configuration in `quiz-app/package.json`
|
||||
- Use Vue single-file components (.vue files)
|
||||
- Maintain component-based architecture
|
||||
- Run `npm run lint` before committing changes
|
||||
|
||||
### Markdown Documentation
|
||||
- Use clear heading hierarchy (# ## ### etc.)
|
||||
- Include code blocks with language specifiers
|
||||
- Add alt text for images
|
||||
- Link to related lessons and resources
|
||||
- Keep line lengths reasonable for readability
|
||||
|
||||
### File Organization
|
||||
- Lesson content in numbered folders (01-defining-data-science, etc.)
|
||||
- Solutions in dedicated `solution/` subfolders
|
||||
- Translations mirror English structure in the `translations/` folder
|
||||
- Keep data files in `data/` or lesson-specific folders
|
||||
|
||||
## Build and Deployment
|
||||
|
||||
### Quiz Application Deployment
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps Deployment
|
||||
The quiz-app can be deployed to Azure Static Web Apps:
|
||||
1. Create an Azure Static Web App resource
|
||||
2. Connect to the GitHub repository
|
||||
3. Configure build settings:
|
||||
- App location: `quiz-app`
|
||||
- Output location: `dist`
|
||||
4. GitHub Actions workflow will auto-deploy on push
|
||||
|
||||
### Documentation Site
|
||||
```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
|
||||
- Repository includes dev container configuration
|
||||
- Codespaces automatically sets up Python and Node.js environment
|
||||
- Open the repository in Codespace via GitHub UI
|
||||
- All dependencies install automatically
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Before Submitting
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR Title Format
|
||||
- Use clear, descriptive titles
|
||||
- Format: `[Component] Brief description`
|
||||
- Examples:
|
||||
- `[Lesson 7] Fix Python notebook import error`
|
||||
- `[Quiz App] Add German translation`
|
||||
- `[Docs] Update README with new prerequisites`
|
||||
|
||||
### Required Checks
|
||||
- Ensure all code runs without errors
|
||||
- Verify notebooks execute completely
|
||||
- Confirm Vue.js apps build successfully
|
||||
- Check that documentation links work
|
||||
- Test quiz application if modified
|
||||
- Verify translations maintain consistent structure
|
||||
|
||||
### Contribution Guidelines
|
||||
- Follow existing code style and patterns
|
||||
- Add explanatory comments for complex logic
|
||||
- Update relevant documentation
|
||||
- Test changes across different lesson modules if applicable
|
||||
- Review the CONTRIBUTING.md file
|
||||
|
||||
## Additional Notes
|
||||
|
||||
### Common Libraries Used
|
||||
- **pandas**: Data manipulation and analysis
|
||||
- **numpy**: Numerical computing
|
||||
- **matplotlib**: Data visualization and plotting
|
||||
- **seaborn**: Statistical data visualization (some lessons)
|
||||
- **scikit-learn**: Machine learning (advanced lessons)
|
||||
|
||||
### Working with Data Files
|
||||
- Data files are located in the `data/` folder or lesson-specific directories
|
||||
- Most notebooks expect data files in relative paths
|
||||
- CSV files are the primary data format
|
||||
- Some lessons use JSON for non-relational data examples
|
||||
|
||||
### Multilingual Support
|
||||
- 40+ language translations via automated GitHub Actions
|
||||
- Translation workflow in `.github/workflows/co-op-translator.yml`
|
||||
- Translations in the `translations/` folder with language codes
|
||||
- Quiz translations in `quiz-app/src/assets/translations/`
|
||||
|
||||
### Development Environment Options
|
||||
1. **Local Development**: Install Python, Jupyter, Node.js locally
|
||||
2. **GitHub Codespaces**: Cloud-based instant development environment
|
||||
3. **VS Code Dev Containers**: Local container-based development
|
||||
4. **Binder**: Launch notebooks in the cloud (if configured)
|
||||
|
||||
### Lesson Content Guidelines
|
||||
- Each lesson is standalone but builds on previous concepts
|
||||
- Pre-lesson quizzes test prior knowledge
|
||||
- Post-lesson quizzes reinforce learning
|
||||
- Assignments provide hands-on practice
|
||||
- Sketchnotes provide visual summaries
|
||||
|
||||
### Troubleshooting Common Issues
|
||||
|
||||
**Jupyter Kernel Issues:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm Install Failures:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Import Errors in Notebooks:**
|
||||
- Verify all required libraries are installed
|
||||
- Check Python version compatibility (Python 3.7+ recommended)
|
||||
- Ensure the virtual environment is activated
|
||||
|
||||
**Docsify Not Loading:**
|
||||
- Verify you're serving from the repository root
|
||||
- Check that `index.html` exists
|
||||
- Ensure proper network access (port 3000)
|
||||
|
||||
### Performance Considerations
|
||||
- Large datasets may take time to load in notebooks
|
||||
- Visualization rendering can be slow for complex plots
|
||||
- Vue.js dev server enables hot-reload for quick iteration
|
||||
- Production builds are optimized and minified
|
||||
|
||||
### Security Notes
|
||||
- No sensitive data or credentials should be committed
|
||||
- Use environment variables for any API keys in cloud lessons
|
||||
- Azure-related lessons may require Azure account credentials
|
||||
- Keep dependencies updated for security patches
|
||||
|
||||
## Contributing to Translations
|
||||
- Automated translations managed via GitHub Actions
|
||||
- Manual corrections are welcome for translation accuracy
|
||||
- Follow the existing translation folder structure
|
||||
- Update quiz links to include the language parameter: `?loc=fr`
|
||||
- Test translated lessons for proper rendering
|
||||
|
||||
## Related Resources
|
||||
- Main curriculum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Discussion Forum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Other Microsoft curricula: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Project Maintenance
|
||||
- Regular updates to keep content current
|
||||
- Community contributions are welcome
|
||||
- Issues tracked on GitHub
|
||||
- PRs reviewed by curriculum maintainers
|
||||
- Monthly content reviews and updates
|
||||
|
||||
---
|
||||
|
||||
**Disclaimer**:
|
||||
This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please note that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not responsible for any misunderstandings or misinterpretations resulting from the use of this translation.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T10:59:35+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "es"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Resumen del Proyecto
|
||||
|
||||
Data Science for Beginners es un plan de estudios completo de 10 semanas y 20 lecciones creado por los Azure Cloud Advocates de Microsoft. El repositorio es un recurso de aprendizaje que enseña conceptos fundamentales de ciencia de datos a través de lecciones basadas en proyectos, incluyendo notebooks de Jupyter, cuestionarios interactivos y tareas prácticas.
|
||||
|
||||
**Tecnologías Clave:**
|
||||
- **Jupyter Notebooks**: Medio principal de aprendizaje utilizando Python 3
|
||||
- **Bibliotecas de Python**: pandas, numpy, matplotlib para análisis y visualización de datos
|
||||
- **Vue.js 2**: Aplicación de cuestionarios (carpeta quiz-app)
|
||||
- **Docsify**: Generador de sitios de documentación para acceso offline
|
||||
- **Node.js/npm**: Gestión de paquetes para componentes JavaScript
|
||||
- **Markdown**: Todo el contenido de las lecciones y documentación
|
||||
|
||||
**Arquitectura:**
|
||||
- Repositorio educativo multilingüe con extensas traducciones
|
||||
- Estructurado en módulos de lecciones (1-Introducción hasta 6-Ciencia-de-Datos-en-el-Mundo)
|
||||
- Cada lección incluye README, notebooks, tareas y cuestionarios
|
||||
- Aplicación de cuestionarios Vue.js independiente para evaluaciones antes/después de las lecciones
|
||||
- Soporte para GitHub Codespaces y contenedores de desarrollo en VS Code
|
||||
|
||||
## Comandos de Configuración
|
||||
|
||||
### Configuración del Repositorio
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Configuración del Entorno de Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Configuración de la Aplicación de Cuestionarios
|
||||
```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
|
||||
```
|
||||
|
||||
### Servidor de Documentación Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Configuración de Proyectos de Visualización
|
||||
Para proyectos de visualización como meaningful-visualizations (lección 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
|
||||
```
|
||||
|
||||
|
||||
## Flujo de Trabajo de Desarrollo
|
||||
|
||||
### Trabajando con Jupyter Notebooks
|
||||
1. Inicia Jupyter en la raíz del repositorio: `jupyter notebook`
|
||||
2. Navega a la carpeta de la lección deseada
|
||||
3. Abre los archivos `.ipynb` para trabajar en los ejercicios
|
||||
4. Los notebooks son autónomos con explicaciones y celdas de código
|
||||
5. La mayoría de los notebooks utilizan pandas, numpy y matplotlib; asegúrate de que estén instalados
|
||||
|
||||
### Estructura de las Lecciones
|
||||
Cada lección típicamente contiene:
|
||||
- `README.md` - Contenido principal de la lección con teoría y ejemplos
|
||||
- `notebook.ipynb` - Ejercicios prácticos en Jupyter notebook
|
||||
- `assignment.ipynb` o `assignment.md` - Tareas prácticas
|
||||
- Carpeta `solution/` - Notebooks y código de solución
|
||||
- Carpeta `images/` - Materiales visuales de apoyo
|
||||
|
||||
### Desarrollo de la Aplicación de Cuestionarios
|
||||
- Aplicación Vue.js 2 con recarga en caliente durante el desarrollo
|
||||
- Cuestionarios almacenados en `quiz-app/src/assets/translations/`
|
||||
- Cada idioma tiene su propia carpeta de traducción (en, fr, es, etc.)
|
||||
- La numeración de los cuestionarios comienza en 0 y llega hasta 39 (40 cuestionarios en total)
|
||||
|
||||
### Agregar Traducciones
|
||||
- Las traducciones se colocan en la carpeta `translations/` en la raíz del repositorio
|
||||
- Cada idioma tiene una estructura completa de lecciones reflejada desde el inglés
|
||||
- Traducción automatizada mediante GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instrucciones de Pruebas
|
||||
|
||||
### Pruebas de la Aplicación de Cuestionarios
|
||||
```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
|
||||
```
|
||||
|
||||
### Pruebas de Notebooks
|
||||
- No existe un marco de pruebas automatizado para notebooks
|
||||
- Validación manual: Ejecuta todas las celdas en secuencia para asegurarte de que no haya errores
|
||||
- Verifica que los archivos de datos sean accesibles y que los resultados se generen correctamente
|
||||
- Comprueba que las visualizaciones se rendericen adecuadamente
|
||||
|
||||
### Pruebas de Documentación
|
||||
```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
|
||||
```
|
||||
|
||||
### Verificaciones de Calidad de Código
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Guías de Estilo de Código
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Sigue las guías de estilo PEP 8 para código Python
|
||||
- Usa nombres de variables claros que expliquen los datos que se están analizando
|
||||
- Incluye celdas de markdown con explicaciones antes de las celdas de código
|
||||
- Mantén las celdas de código enfocadas en conceptos u operaciones individuales
|
||||
- Utiliza pandas para manipulación de datos, matplotlib para visualización
|
||||
- Patrón común de importación:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Sigue la guía de estilo de Vue.js 2 y las mejores prácticas
|
||||
- Configuración de ESLint en `quiz-app/package.json`
|
||||
- Usa componentes de archivo único de Vue (.vue files)
|
||||
- Mantén una arquitectura basada en componentes
|
||||
- Ejecuta `npm run lint` antes de confirmar cambios
|
||||
|
||||
### Documentación en Markdown
|
||||
- Usa una jerarquía clara de encabezados (# ## ### etc.)
|
||||
- Incluye bloques de código con especificadores de lenguaje
|
||||
- Agrega texto alternativo para imágenes
|
||||
- Enlaza a lecciones y recursos relacionados
|
||||
- Mantén longitudes de línea razonables para facilitar la lectura
|
||||
|
||||
### Organización de Archivos
|
||||
- Contenido de las lecciones en carpetas numeradas (01-definiendo-ciencia-de-datos, etc.)
|
||||
- Soluciones en subcarpetas dedicadas `solution/`
|
||||
- Las traducciones reflejan la estructura en inglés en la carpeta `translations/`
|
||||
- Mantén los archivos de datos en `data/` o carpetas específicas de las lecciones
|
||||
|
||||
## Construcción y Despliegue
|
||||
|
||||
### Despliegue de la Aplicación de Cuestionarios
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Despliegue de Azure Static Web Apps
|
||||
La aplicación quiz-app puede desplegarse en Azure Static Web Apps:
|
||||
1. Crea un recurso de Azure Static Web App
|
||||
2. Conéctalo al repositorio de GitHub
|
||||
3. Configura los ajustes de construcción:
|
||||
- Ubicación de la aplicación: `quiz-app`
|
||||
- Ubicación de salida: `dist`
|
||||
4. El flujo de trabajo de GitHub Actions se encargará del despliegue automático al realizar un push
|
||||
|
||||
### Sitio de Documentación
|
||||
```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
|
||||
- El repositorio incluye configuración de contenedor de desarrollo
|
||||
- Codespaces configura automáticamente el entorno de Python y Node.js
|
||||
- Abre el repositorio en Codespace a través de la interfaz de GitHub
|
||||
- Todas las dependencias se instalan automáticamente
|
||||
|
||||
## Guías para Pull Requests
|
||||
|
||||
### Antes de Enviar
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Formato del Título de PR
|
||||
- Usa títulos claros y descriptivos
|
||||
- Formato: `[Componente] Breve descripción`
|
||||
- Ejemplos:
|
||||
- `[Lección 7] Corrige error de importación en notebook de Python`
|
||||
- `[Aplicación de Cuestionarios] Agrega traducción al alemán`
|
||||
- `[Documentación] Actualiza README con nuevos requisitos`
|
||||
|
||||
### Verificaciones Requeridas
|
||||
- Asegúrate de que todo el código se ejecute sin errores
|
||||
- Verifica que los notebooks se ejecuten completamente
|
||||
- Confirma que las aplicaciones Vue.js se construyan correctamente
|
||||
- Comprueba que los enlaces de la documentación funcionen
|
||||
- Prueba la aplicación de cuestionarios si fue modificada
|
||||
- Verifica que las traducciones mantengan una estructura consistente
|
||||
|
||||
### Guías de Contribución
|
||||
- Sigue el estilo y los patrones de código existentes
|
||||
- Agrega comentarios explicativos para lógica compleja
|
||||
- Actualiza la documentación relevante
|
||||
- Prueba los cambios en diferentes módulos de lecciones si aplica
|
||||
- Revisa el archivo CONTRIBUTING.md
|
||||
|
||||
## Notas Adicionales
|
||||
|
||||
### Bibliotecas Comunes Utilizadas
|
||||
- **pandas**: Manipulación y análisis de datos
|
||||
- **numpy**: Computación numérica
|
||||
- **matplotlib**: Visualización y gráficos de datos
|
||||
- **seaborn**: Visualización estadística de datos (algunas lecciones)
|
||||
- **scikit-learn**: Aprendizaje automático (lecciones avanzadas)
|
||||
|
||||
### Trabajando con Archivos de Datos
|
||||
- Archivos de datos ubicados en la carpeta `data/` o directorios específicos de las lecciones
|
||||
- La mayoría de los notebooks esperan archivos de datos en rutas relativas
|
||||
- Los archivos CSV son el formato principal de datos
|
||||
- Algunas lecciones utilizan JSON para ejemplos de datos no relacionales
|
||||
|
||||
### Soporte Multilingüe
|
||||
- Más de 40 traducciones de idiomas mediante GitHub Actions automatizadas
|
||||
- Flujo de trabajo de traducción en `.github/workflows/co-op-translator.yml`
|
||||
- Traducciones en la carpeta `translations/` con códigos de idioma
|
||||
- Traducciones de cuestionarios en `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opciones de Entorno de Desarrollo
|
||||
1. **Desarrollo Local**: Instala Python, Jupyter, Node.js localmente
|
||||
2. **GitHub Codespaces**: Entorno de desarrollo instantáneo basado en la nube
|
||||
3. **Contenedores de Desarrollo en VS Code**: Desarrollo local basado en contenedores
|
||||
4. **Binder**: Lanza notebooks en la nube (si está configurado)
|
||||
|
||||
### Guías de Contenido de las Lecciones
|
||||
- Cada lección es autónoma pero se basa en conceptos previos
|
||||
- Cuestionarios previos a la lección evalúan conocimientos previos
|
||||
- Cuestionarios posteriores a la lección refuerzan el aprendizaje
|
||||
- Las tareas proporcionan práctica práctica
|
||||
- Los sketchnotes ofrecen resúmenes visuales
|
||||
|
||||
### Solución de Problemas Comunes
|
||||
|
||||
**Problemas con el Kernel de Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Fallos en npm Install:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Errores de Importación en Notebooks:**
|
||||
- Verifica que todas las bibliotecas requeridas estén instaladas
|
||||
- Comprueba la compatibilidad de la versión de Python (se recomienda Python 3.7+)
|
||||
- Asegúrate de que el entorno virtual esté activado
|
||||
|
||||
**Docsify No Carga:**
|
||||
- Verifica que estés sirviendo desde la raíz del repositorio
|
||||
- Comprueba que `index.html` exista
|
||||
- Asegúrate de tener acceso adecuado a la red (puerto 3000)
|
||||
|
||||
### Consideraciones de Rendimiento
|
||||
- Los conjuntos de datos grandes pueden tardar en cargarse en los notebooks
|
||||
- La renderización de visualizaciones puede ser lenta para gráficos complejos
|
||||
- El servidor de desarrollo de Vue.js permite recarga en caliente para iteración rápida
|
||||
- Las construcciones de producción están optimizadas y minificadas
|
||||
|
||||
### Notas de Seguridad
|
||||
- No se deben comprometer datos sensibles ni credenciales
|
||||
- Usa variables de entorno para cualquier clave API en lecciones en la nube
|
||||
- Las lecciones relacionadas con Azure pueden requerir credenciales de cuenta de Azure
|
||||
- Mantén las dependencias actualizadas para parches de seguridad
|
||||
|
||||
## Contribuyendo a las Traducciones
|
||||
- Traducciones automatizadas gestionadas mediante GitHub Actions
|
||||
- Correcciones manuales son bienvenidas para mejorar la precisión de las traducciones
|
||||
- Sigue la estructura de carpetas de traducción existente
|
||||
- Actualiza los enlaces de los cuestionarios para incluir el parámetro de idioma: `?loc=fr`
|
||||
- Prueba las lecciones traducidas para verificar su correcta visualización
|
||||
|
||||
## Recursos Relacionados
|
||||
- Plan de estudios principal: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Foro de Discusión: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Otros planes de estudios de Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Mantenimiento del Proyecto
|
||||
- Actualizaciones regulares para mantener el contenido actualizado
|
||||
- Contribuciones de la comunidad son bienvenidas
|
||||
- Problemas rastreados en GitHub
|
||||
- PRs revisados por los mantenedores del plan de estudios
|
||||
- Revisiones y actualizaciones de contenido mensuales
|
||||
|
||||
---
|
||||
|
||||
**Descargo de responsabilidad**:
|
||||
Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por garantizar la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o imprecisiones. El documento original en su idioma nativo debe considerarse como la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por humanos. No nos hacemos responsables de malentendidos o interpretaciones erróneas que puedan surgir del uso de esta traducción.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:27:05+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "fi"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Projektin yleiskatsaus
|
||||
|
||||
Data Science for Beginners on Microsoft Azure Cloud Advocatesin luoma kattava 10 viikon, 20 oppitunnin opetusohjelma. Tämä repositorio on oppimisresurssi, joka opettaa perustavanlaatuisia datatieteen käsitteitä projektipohjaisten oppituntien avulla, mukaan lukien Jupyter-muistikirjat, interaktiiviset visailut ja käytännön tehtävät.
|
||||
|
||||
**Keskeiset teknologiat:**
|
||||
- **Jupyter-muistikirjat**: Pääasiallinen oppimisväline Python 3:lla
|
||||
- **Python-kirjastot**: pandas, numpy, matplotlib datan analysointiin ja visualisointiin
|
||||
- **Vue.js 2**: Visailusovellus (quiz-app-kansio)
|
||||
- **Docsify**: Dokumentaation sivustogeneraattori offline-käyttöön
|
||||
- **Node.js/npm**: JavaScript-komponenttien pakettien hallinta
|
||||
- **Markdown**: Kaikki oppituntien sisältö ja dokumentaatio
|
||||
|
||||
**Arkkitehtuuri:**
|
||||
- Monikielinen opetusrepositorio laajoilla käännöksillä
|
||||
- Jäsennelty oppituntimoduuleihin (1-Introduction - 6-Data-Science-In-Wild)
|
||||
- Jokainen oppitunti sisältää README:n, muistikirjat, tehtävät ja visailut
|
||||
- Erillinen Vue.js-visailusovellus oppituntien arviointiin ennen ja jälkeen
|
||||
- GitHub Codespaces ja VS Code -kehityskonttien tuki
|
||||
|
||||
## Asennuskomennot
|
||||
|
||||
### Repositorion asennus
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python-ympäristön asennus
|
||||
```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
|
||||
```
|
||||
|
||||
### Visailusovelluksen asennus
|
||||
```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-dokumentaatiopalvelin
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Visualisointiprojektien asennus
|
||||
Visualisointiprojekteille, kuten meaningful-visualizations (oppitunti 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
|
||||
```
|
||||
|
||||
|
||||
## Kehitystyön kulku
|
||||
|
||||
### Työskentely Jupyter-muistikirjojen kanssa
|
||||
1. Käynnistä Jupyter repositorion juurihakemistossa: `jupyter notebook`
|
||||
2. Siirry haluttuun oppituntikansioon
|
||||
3. Avaa `.ipynb`-tiedostot harjoitusten tekemistä varten
|
||||
4. Muistikirjat ovat itsenäisiä ja sisältävät selityksiä sekä koodisoluja
|
||||
5. Useimmat muistikirjat käyttävät pandas-, numpy- ja matplotlib-kirjastoja - varmista, että ne on asennettu
|
||||
|
||||
### Oppituntien rakenne
|
||||
Jokainen oppitunti sisältää yleensä:
|
||||
- `README.md` - Pääsisältö teoriaa ja esimerkkejä varten
|
||||
- `notebook.ipynb` - Käytännön Jupyter-muistikirjaharjoituksia
|
||||
- `assignment.ipynb` tai `assignment.md` - Harjoitustehtäviä
|
||||
- `solution/`-kansio - Ratkaisumuistikirjat ja koodi
|
||||
- `images/`-kansio - Tukimateriaalit
|
||||
|
||||
### Visailusovelluksen kehitys
|
||||
- Vue.js 2 -sovellus, jossa on hot-reload kehityksen aikana
|
||||
- Visailut tallennetaan `quiz-app/src/assets/translations/`-kansioon
|
||||
- Jokaisella kielellä on oma käännöskansio (en, fr, es jne.)
|
||||
- Visailujen numerointi alkaa 0:sta ja jatkuu 39:ään (yhteensä 40 visailua)
|
||||
|
||||
### Käännösten lisääminen
|
||||
- Käännökset sijoitetaan `translations/`-kansioon repositorion juurihakemistossa
|
||||
- Jokaisella kielellä on täydellinen oppituntirakenne, joka peilaa englanninkielistä
|
||||
- Automaattinen käännös GitHub Actionsin kautta (co-op-translator.yml)
|
||||
|
||||
## Testausohjeet
|
||||
|
||||
### Visailusovelluksen testaus
|
||||
```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
|
||||
```
|
||||
|
||||
### Muistikirjojen testaus
|
||||
- Muistikirjoille ei ole olemassa automaattista testauskehystä
|
||||
- Manuaalinen validointi: Suorita kaikki solut järjestyksessä varmistaaksesi, ettei virheitä esiinny
|
||||
- Varmista, että datatiedostot ovat saatavilla ja tulokset luodaan oikein
|
||||
- Tarkista, että visualisoinnit renderöityvät oikein
|
||||
|
||||
### Dokumentaation testaus
|
||||
```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
|
||||
```
|
||||
|
||||
### Koodin laadun tarkistukset
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Koodityyliohjeet
|
||||
|
||||
### Python (Jupyter-muistikirjat)
|
||||
- Noudata PEP 8 -tyyliohjeita Python-koodissa
|
||||
- Käytä selkeitä muuttujanimiä, jotka kuvaavat analysoitavaa dataa
|
||||
- Sisällytä markdown-solut selityksillä ennen koodisoluja
|
||||
- Pidä koodisolut keskittyneinä yksittäisiin käsitteisiin tai operaatioihin
|
||||
- Käytä pandas-kirjastoa datan käsittelyyn ja matplotlib-kirjastoa visualisointiin
|
||||
- Yleinen tuontimalli:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Noudata Vue.js 2 -tyyliopasta ja parhaita käytäntöjä
|
||||
- ESLint-konfiguraatio `quiz-app/package.json`-tiedostossa
|
||||
- Käytä Vue-yksittäistiedostokomponentteja (.vue-tiedostot)
|
||||
- Säilytä komponenttipohjainen arkkitehtuuri
|
||||
- Suorita `npm run lint` ennen muutosten lähettämistä
|
||||
|
||||
### Markdown-dokumentaatio
|
||||
- Käytä selkeää otsikkohierarkiaa (# ## ### jne.)
|
||||
- Sisällytä koodilohkot kielimäärityksillä
|
||||
- Lisää kuville alt-teksti
|
||||
- Linkitä liittyviin oppitunteihin ja resursseihin
|
||||
- Pidä rivin pituudet kohtuullisina luettavuuden vuoksi
|
||||
|
||||
### Tiedostojen organisointi
|
||||
- Oppituntisisältö numeroiduissa kansioissa (01-defining-data-science jne.)
|
||||
- Ratkaisut omissa `solution/`-alikansioissaan
|
||||
- Käännökset peilaavat englanninkielistä rakennetta `translations/`-kansiossa
|
||||
- Datatiedostot `data/`-kansiossa tai oppituntikohtaisissa kansioissa
|
||||
|
||||
## Rakentaminen ja käyttöönotto
|
||||
|
||||
### Visailusovelluksen käyttöönotto
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps -käyttöönotto
|
||||
Visailusovellus voidaan ottaa käyttöön Azure Static Web Appsissa:
|
||||
1. Luo Azure Static Web App -resurssi
|
||||
2. Yhdistä GitHub-repositorioon
|
||||
3. Määritä rakennusasetukset:
|
||||
- Sovelluksen sijainti: `quiz-app`
|
||||
- Tulosteen sijainti: `dist`
|
||||
4. GitHub Actions -työnkulku ottaa käyttöön automaattisesti pushin yhteydessä
|
||||
|
||||
### Dokumentaatiosivusto
|
||||
```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
|
||||
- Repositorio sisältää kehityskonttien konfiguraation
|
||||
- Codespaces asentaa automaattisesti Python- ja Node.js-ympäristön
|
||||
- Avaa repositorio Codespacessa GitHubin käyttöliittymän kautta
|
||||
- Kaikki riippuvuudet asennetaan automaattisesti
|
||||
|
||||
## Pull Request -ohjeet
|
||||
|
||||
### Ennen lähettämistä
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR-otsikon muoto
|
||||
- Käytä selkeitä, kuvaavia otsikoita
|
||||
- Muoto: `[Komponentti] Lyhyt kuvaus`
|
||||
- Esimerkkejä:
|
||||
- `[Oppitunti 7] Korjaa Python-muistikirjan tuontivirhe`
|
||||
- `[Visailusovellus] Lisää saksankielinen käännös`
|
||||
- `[Dokumentaatio] Päivitä README uusilla vaatimuksilla`
|
||||
|
||||
### Vaaditut tarkistukset
|
||||
- Varmista, että kaikki koodi toimii ilman virheitä
|
||||
- Tarkista, että muistikirjat suorittavat kokonaan
|
||||
- Varmista, että Vue.js-sovellukset rakentuvat onnistuneesti
|
||||
- Tarkista, että dokumentaatiolinkit toimivat
|
||||
- Testaa visailusovellus, jos sitä on muokattu
|
||||
- Varmista, että käännökset säilyttävät yhtenäisen rakenteen
|
||||
|
||||
### Osallistumisohjeet
|
||||
- Noudata olemassa olevia koodityylejä ja -malleja
|
||||
- Lisää selittäviä kommentteja monimutkaiselle logiikalle
|
||||
- Päivitä asiaankuuluva dokumentaatio
|
||||
- Testaa muutokset eri oppituntimoduuleissa, jos sovellettavissa
|
||||
- Lue CONTRIBUTING.md-tiedosto
|
||||
|
||||
## Lisähuomautuksia
|
||||
|
||||
### Yleisesti käytetyt kirjastot
|
||||
- **pandas**: Datan käsittely ja analysointi
|
||||
- **numpy**: Laskennallinen matematiikka
|
||||
- **matplotlib**: Datan visualisointi ja kaavioiden luonti
|
||||
- **seaborn**: Tilastollinen datan visualisointi (joissakin oppitunneissa)
|
||||
- **scikit-learn**: Koneoppiminen (edistyneet oppitunnit)
|
||||
|
||||
### Työskentely datatiedostojen kanssa
|
||||
- Datatiedostot sijaitsevat `data/`-kansiossa tai oppituntikohtaisissa hakemistoissa
|
||||
- Useimmat muistikirjat odottavat datatiedostoja suhteellisissa poluissa
|
||||
- CSV-tiedostot ovat ensisijainen datamuoto
|
||||
- Joissakin oppitunneissa käytetään JSON-tiedostoja ei-relationaalisen datan esimerkkeinä
|
||||
|
||||
### Monikielinen tuki
|
||||
- Yli 40 kielen käännökset automaattisesti GitHub Actionsin kautta
|
||||
- Käännöstyönkulku `.github/workflows/co-op-translator.yml`-tiedostossa
|
||||
- Käännökset `translations/`-kansiossa kielikoodeilla
|
||||
- Visailukäännökset `quiz-app/src/assets/translations/`-kansiossa
|
||||
|
||||
### Kehitysympäristön vaihtoehdot
|
||||
1. **Paikallinen kehitys**: Asenna Python, Jupyter, Node.js paikallisesti
|
||||
2. **GitHub Codespaces**: Pilvipohjainen välitön kehitysympäristö
|
||||
3. **VS Code Dev Containers**: Paikallinen konttipohjainen kehitys
|
||||
4. **Binder**: Käynnistä muistikirjat pilvessä (jos konfiguroitu)
|
||||
|
||||
### Oppituntisisällön ohjeet
|
||||
- Jokainen oppitunti on itsenäinen, mutta rakentuu aiempien käsitteiden päälle
|
||||
- Ennakkovisailut testaavat aiempaa tietämystä
|
||||
- Jälkivisailut vahvistavat oppimista
|
||||
- Tehtävät tarjoavat käytännön harjoitusta
|
||||
- Sketchnotes tarjoaa visuaalisia yhteenvetoja
|
||||
|
||||
### Yleiset ongelmatilanteet
|
||||
|
||||
**Jupyter-ytimen ongelmat:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm-asennuksen epäonnistumiset:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Tuontivirheet muistikirjoissa:**
|
||||
- Varmista, että kaikki tarvittavat kirjastot on asennettu
|
||||
- Tarkista Python-version yhteensopivuus (suositus: Python 3.7+)
|
||||
- Varmista, että virtuaaliympäristö on aktivoitu
|
||||
|
||||
**Docsify ei lataudu:**
|
||||
- Varmista, että palvelin toimii repositorion juurihakemistosta
|
||||
- Tarkista, että `index.html`-tiedosto on olemassa
|
||||
- Varmista oikea verkkoyhteys (portti 3000)
|
||||
|
||||
### Suorituskykyhuomautukset
|
||||
- Suuret datatiedostot voivat kestää aikaa latautua muistikirjoissa
|
||||
- Visualisointien renderöinti voi olla hidasta monimutkaisille kaavioille
|
||||
- Vue.js-kehityspalvelin mahdollistaa nopean iteroinnin hot-reloadin avulla
|
||||
- Tuotantoversiot ovat optimoituja ja pienennettyjä
|
||||
|
||||
### Tietoturvahuomautukset
|
||||
- Älä tallenna arkaluontoisia tietoja tai tunnuksia
|
||||
- Käytä ympäristömuuttujia pilvioppituntien API-avaimille
|
||||
- Azureen liittyvät oppitunnit saattavat vaatia Azure-tilin tunnuksia
|
||||
- Pidä riippuvuudet ajan tasalla tietoturvapäivitysten varalta
|
||||
|
||||
## Osallistuminen käännöksiin
|
||||
- Automaattiset käännökset hallinnoidaan GitHub Actionsin kautta
|
||||
- Manuaaliset korjaukset ovat tervetulleita käännösten tarkkuuden parantamiseksi
|
||||
- Noudata olemassa olevaa käännöskansiota
|
||||
- Päivitä visailulinkit sisältämään kieliparametri: `?loc=fr`
|
||||
- Testaa käännetyt oppitunnit varmistaaksesi oikean renderöinnin
|
||||
|
||||
## Liittyvät resurssit
|
||||
- Pääopetusohjelma: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Keskustelufoorumi: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Muut Microsoftin opetusohjelmat: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Projektin ylläpito
|
||||
- Säännölliset päivitykset sisällön ajantasaisena pitämiseksi
|
||||
- Yhteisön panokset ovat tervetulleita
|
||||
- Ongelmia seurataan GitHubissa
|
||||
- PR:t tarkistetaan opetusohjelman ylläpitäjien toimesta
|
||||
- Kuukausittaiset sisällön tarkistukset ja päivitykset
|
||||
|
||||
---
|
||||
|
||||
**Vastuuvapauslauseke**:
|
||||
Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, huomioithan, että automaattiset käännökset voivat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäisellä kielellä tulisi pitää ensisijaisena lähteenä. Kriittisen tiedon osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa väärinkäsityksistä tai virhetulkinnoista, jotka johtuvat tämän käännöksen käytöstä.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T10:58:33+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "fr"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Aperçu du projet
|
||||
|
||||
Data Science for Beginners est un programme complet de 10 semaines et 20 leçons créé par les Cloud Advocates de Microsoft Azure. Le dépôt est une ressource d'apprentissage qui enseigne les concepts fondamentaux de la science des données à travers des leçons basées sur des projets, incluant des notebooks Jupyter, des quiz interactifs et des exercices pratiques.
|
||||
|
||||
**Technologies clés :**
|
||||
- **Jupyter Notebooks** : Principal support d'apprentissage utilisant Python 3
|
||||
- **Bibliothèques Python** : pandas, numpy, matplotlib pour l'analyse et la visualisation des données
|
||||
- **Vue.js 2** : Application de quiz (dossier quiz-app)
|
||||
- **Docsify** : Générateur de site de documentation pour un accès hors ligne
|
||||
- **Node.js/npm** : Gestion des packages pour les composants JavaScript
|
||||
- **Markdown** : Tout le contenu des leçons et la documentation
|
||||
|
||||
**Architecture :**
|
||||
- Dépôt éducatif multilingue avec de nombreuses traductions
|
||||
- Structuré en modules de leçons (1-Introduction à 6-Data-Science-In-Wild)
|
||||
- Chaque leçon inclut un README, des notebooks, des exercices et des quiz
|
||||
- Application de quiz Vue.js autonome pour les évaluations avant/après leçon
|
||||
- Support pour GitHub Codespaces et les conteneurs de développement VS Code
|
||||
|
||||
## Commandes d'installation
|
||||
|
||||
### Configuration du dépôt
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Configuration de l'environnement Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Configuration de l'application de quiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Serveur de documentation Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Configuration des projets de visualisation
|
||||
Pour les projets de visualisation comme meaningful-visualizations (leçon 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
|
||||
```
|
||||
|
||||
|
||||
## Flux de travail de développement
|
||||
|
||||
### Travailler avec les notebooks Jupyter
|
||||
1. Démarrez Jupyter à la racine du dépôt : `jupyter notebook`
|
||||
2. Naviguez vers le dossier de la leçon souhaitée
|
||||
3. Ouvrez les fichiers `.ipynb` pour travailler sur les exercices
|
||||
4. Les notebooks sont autonomes avec des explications et des cellules de code
|
||||
5. La plupart des notebooks utilisent pandas, numpy et matplotlib - assurez-vous qu'ils sont installés
|
||||
|
||||
### Structure des leçons
|
||||
Chaque leçon contient généralement :
|
||||
- `README.md` - Contenu principal de la leçon avec théorie et exemples
|
||||
- `notebook.ipynb` - Exercices pratiques dans un notebook Jupyter
|
||||
- `assignment.ipynb` ou `assignment.md` - Exercices pratiques
|
||||
- Dossier `solution/` - Notebooks et code de solution
|
||||
- Dossier `images/` - Matériaux visuels de support
|
||||
|
||||
### Développement de l'application de quiz
|
||||
- Application Vue.js 2 avec rechargement à chaud pendant le développement
|
||||
- Les quiz sont stockés dans `quiz-app/src/assets/translations/`
|
||||
- Chaque langue a son propre dossier de traduction (en, fr, es, etc.)
|
||||
- La numérotation des quiz commence à 0 et va jusqu'à 39 (40 quiz au total)
|
||||
|
||||
### Ajouter des traductions
|
||||
- Les traductions se trouvent dans le dossier `translations/` à la racine du dépôt
|
||||
- Chaque langue a une structure complète de leçons miroir de l'anglais
|
||||
- Traduction automatisée via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instructions de test
|
||||
|
||||
### Test de l'application de quiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Test des notebooks
|
||||
- Aucun cadre de test automatisé n'existe pour les notebooks
|
||||
- Validation manuelle : Exécutez toutes les cellules dans l'ordre pour vérifier qu'il n'y a pas d'erreurs
|
||||
- Vérifiez que les fichiers de données sont accessibles et que les sorties sont générées correctement
|
||||
- Assurez-vous que les visualisations s'affichent correctement
|
||||
|
||||
### Test de la documentation
|
||||
```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
|
||||
```
|
||||
|
||||
### Vérifications de la qualité du code
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Directives de style de code
|
||||
|
||||
### Python (Notebooks Jupyter)
|
||||
- Suivez les directives de style PEP 8 pour le code Python
|
||||
- Utilisez des noms de variables clairs qui expliquent les données analysées
|
||||
- Incluez des cellules Markdown avec des explications avant les cellules de code
|
||||
- Gardez les cellules de code centrées sur des concepts ou opérations uniques
|
||||
- Utilisez pandas pour la manipulation des données, matplotlib pour la visualisation
|
||||
- Modèle d'importation commun :
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Suivez le guide de style Vue.js 2 et les meilleures pratiques
|
||||
- Configuration ESLint dans `quiz-app/package.json`
|
||||
- Utilisez des composants Vue à fichier unique (.vue)
|
||||
- Maintenez une architecture basée sur les composants
|
||||
- Exécutez `npm run lint` avant de valider les modifications
|
||||
|
||||
### Documentation Markdown
|
||||
- Utilisez une hiérarchie claire des titres (# ## ### etc.)
|
||||
- Incluez des blocs de code avec des spécificateurs de langage
|
||||
- Ajoutez du texte alternatif pour les images
|
||||
- Liez les leçons et ressources connexes
|
||||
- Gardez des longueurs de ligne raisonnables pour la lisibilité
|
||||
|
||||
### Organisation des fichiers
|
||||
- Contenu des leçons dans des dossiers numérotés (01-defining-data-science, etc.)
|
||||
- Solutions dans des sous-dossiers dédiés `solution/`
|
||||
- Les traductions reflètent la structure anglaise dans le dossier `translations/`
|
||||
- Gardez les fichiers de données dans `data/` ou des dossiers spécifiques aux leçons
|
||||
|
||||
## Construction et déploiement
|
||||
|
||||
### Déploiement de l'application de quiz
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Déploiement Azure Static Web Apps
|
||||
L'application de quiz peut être déployée sur Azure Static Web Apps :
|
||||
1. Créez une ressource Azure Static Web App
|
||||
2. Connectez-vous au dépôt GitHub
|
||||
3. Configurez les paramètres de construction :
|
||||
- Emplacement de l'application : `quiz-app`
|
||||
- Emplacement de sortie : `dist`
|
||||
4. Le workflow GitHub Actions déploiera automatiquement lors d'un push
|
||||
|
||||
### Site de documentation
|
||||
```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
|
||||
- Le dépôt inclut une configuration de conteneur de développement
|
||||
- Codespaces configure automatiquement l'environnement Python et Node.js
|
||||
- Ouvrez le dépôt dans Codespace via l'interface GitHub
|
||||
- Toutes les dépendances s'installent automatiquement
|
||||
|
||||
## Directives pour les pull requests
|
||||
|
||||
### Avant de soumettre
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format du titre de la PR
|
||||
- Utilisez des titres clairs et descriptifs
|
||||
- Format : `[Composant] Brève description`
|
||||
- Exemples :
|
||||
- `[Leçon 7] Corrige l'erreur d'importation du notebook Python`
|
||||
- `[Application de quiz] Ajoute la traduction en allemand`
|
||||
- `[Docs] Met à jour le README avec les nouveaux prérequis`
|
||||
|
||||
### Vérifications requises
|
||||
- Assurez-vous que tout le code s'exécute sans erreurs
|
||||
- Vérifiez que les notebooks s'exécutent complètement
|
||||
- Confirmez que les applications Vue.js se construisent avec succès
|
||||
- Vérifiez que les liens de la documentation fonctionnent
|
||||
- Testez l'application de quiz si elle a été modifiée
|
||||
- Vérifiez que les traductions maintiennent une structure cohérente
|
||||
|
||||
### Directives de contribution
|
||||
- Suivez le style et les modèles de code existants
|
||||
- Ajoutez des commentaires explicatifs pour les logiques complexes
|
||||
- Mettez à jour la documentation pertinente
|
||||
- Testez les modifications dans différents modules de leçons si applicable
|
||||
- Consultez le fichier CONTRIBUTING.md
|
||||
|
||||
## Notes supplémentaires
|
||||
|
||||
### Bibliothèques couramment utilisées
|
||||
- **pandas** : Manipulation et analyse des données
|
||||
- **numpy** : Calcul numérique
|
||||
- **matplotlib** : Visualisation et tracé des données
|
||||
- **seaborn** : Visualisation statistique des données (certaines leçons)
|
||||
- **scikit-learn** : Apprentissage automatique (leçons avancées)
|
||||
|
||||
### Travailler avec les fichiers de données
|
||||
- Les fichiers de données se trouvent dans le dossier `data/` ou dans des répertoires spécifiques aux leçons
|
||||
- La plupart des notebooks attendent des fichiers de données dans des chemins relatifs
|
||||
- Les fichiers CSV sont le format de données principal
|
||||
- Certaines leçons utilisent JSON pour des exemples de données non relationnelles
|
||||
|
||||
### Support multilingue
|
||||
- Plus de 40 traductions linguistiques via GitHub Actions automatisés
|
||||
- Workflow de traduction dans `.github/workflows/co-op-translator.yml`
|
||||
- Traductions dans le dossier `translations/` avec des codes de langue
|
||||
- Traductions des quiz dans `quiz-app/src/assets/translations/`
|
||||
|
||||
### Options d'environnement de développement
|
||||
1. **Développement local** : Installez Python, Jupyter, Node.js localement
|
||||
2. **GitHub Codespaces** : Environnement de développement instantané basé sur le cloud
|
||||
3. **Conteneurs de développement VS Code** : Développement local basé sur des conteneurs
|
||||
4. **Binder** : Lancez les notebooks dans le cloud (si configuré)
|
||||
|
||||
### Directives de contenu des leçons
|
||||
- Chaque leçon est autonome mais s'appuie sur des concepts précédents
|
||||
- Les quiz avant la leçon testent les connaissances préalables
|
||||
- Les quiz après la leçon renforcent l'apprentissage
|
||||
- Les exercices offrent une pratique concrète
|
||||
- Les sketchnotes fournissent des résumés visuels
|
||||
|
||||
### Résolution des problèmes courants
|
||||
|
||||
**Problèmes de noyau Jupyter :**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Échecs d'installation npm :**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Erreurs d'importation dans les notebooks :**
|
||||
- Vérifiez que toutes les bibliothèques requises sont installées
|
||||
- Vérifiez la compatibilité de la version Python (Python 3.7+ recommandé)
|
||||
- Assurez-vous que l'environnement virtuel est activé
|
||||
|
||||
**Docsify ne se charge pas :**
|
||||
- Vérifiez que vous servez depuis la racine du dépôt
|
||||
- Assurez-vous que `index.html` existe
|
||||
- Vérifiez l'accès réseau approprié (port 3000)
|
||||
|
||||
### Considérations de performance
|
||||
- Les grands ensembles de données peuvent prendre du temps à charger dans les notebooks
|
||||
- Le rendu des visualisations peut être lent pour les tracés complexes
|
||||
- Le serveur de développement Vue.js permet un rechargement à chaud pour une itération rapide
|
||||
- Les constructions de production sont optimisées et minifiées
|
||||
|
||||
### Notes de sécurité
|
||||
- Aucune donnée sensible ou identifiant ne doit être soumis
|
||||
- Utilisez des variables d'environnement pour les clés API dans les leçons cloud
|
||||
- Les leçons liées à Azure peuvent nécessiter des identifiants de compte Azure
|
||||
- Gardez les dépendances à jour pour les correctifs de sécurité
|
||||
|
||||
## Contribuer aux traductions
|
||||
- Les traductions automatisées sont gérées via GitHub Actions
|
||||
- Les corrections manuelles sont les bienvenues pour améliorer la précision des traductions
|
||||
- Suivez la structure existante des dossiers de traduction
|
||||
- Mettez à jour les liens des quiz pour inclure le paramètre de langue : `?loc=fr`
|
||||
- Testez les leçons traduites pour un rendu correct
|
||||
|
||||
## Ressources connexes
|
||||
- Programme principal : https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn : https://docs.microsoft.com/learn/
|
||||
- Student Hub : https://docs.microsoft.com/learn/student-hub
|
||||
- Forum de discussion : https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Autres programmes Microsoft : ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Maintenance du projet
|
||||
- Mises à jour régulières pour garder le contenu à jour
|
||||
- Contributions de la communauté bienvenues
|
||||
- Problèmes suivis sur GitHub
|
||||
- PRs examinées par les mainteneurs du programme
|
||||
- Revues et mises à jour mensuelles du contenu
|
||||
|
||||
---
|
||||
|
||||
**Avertissement** :
|
||||
Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforcions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d'origine doit être considéré comme la source faisant autorité. Pour des informations critiques, il est recommandé de recourir à une traduction humaine professionnelle. Nous déclinons toute responsabilité en cas de malentendus ou d'interprétations erronées résultant de l'utilisation de cette traduction.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:11:12+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "hi"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## परियोजना का अवलोकन
|
||||
|
||||
बिगिनर्स के लिए डेटा साइंस एक व्यापक 10-सप्ताह, 20-पाठ का पाठ्यक्रम है जिसे Microsoft Azure Cloud Advocates द्वारा बनाया गया है। यह रिपॉजिटरी एक शिक्षण संसाधन है जो प्रोजेक्ट-आधारित पाठों के माध्यम से डेटा साइंस की बुनियादी अवधारणाओं को सिखाता है, जिसमें Jupyter नोटबुक, इंटरएक्टिव क्विज़ और प्रैक्टिकल असाइनमेंट शामिल हैं।
|
||||
|
||||
**मुख्य तकनीकें:**
|
||||
- **Jupyter नोटबुक**: Python 3 का उपयोग करके प्राथमिक शिक्षण माध्यम
|
||||
- **Python लाइब्रेरीज़**: डेटा विश्लेषण और विज़ुअलाइज़ेशन के लिए pandas, numpy, matplotlib
|
||||
- **Vue.js 2**: क्विज़ एप्लिकेशन (quiz-app फ़ोल्डर)
|
||||
- **Docsify**: ऑफलाइन एक्सेस के लिए डॉक्यूमेंटेशन साइट जनरेटर
|
||||
- **Node.js/npm**: जावास्क्रिप्ट घटकों के लिए पैकेज प्रबंधन
|
||||
- **Markdown**: सभी पाठ सामग्री और डॉक्यूमेंटेशन
|
||||
|
||||
**आर्किटेक्चर:**
|
||||
- बहु-भाषा शैक्षिक रिपॉजिटरी जिसमें व्यापक अनुवाद शामिल हैं
|
||||
- पाठ मॉड्यूल में संरचित (1-Introduction से 6-Data-Science-In-Wild तक)
|
||||
- प्रत्येक पाठ में README, नोटबुक, असाइनमेंट और क्विज़ शामिल हैं
|
||||
- प्री/पोस्ट-पाठ आकलन के लिए स्वतंत्र Vue.js क्विज़ एप्लिकेशन
|
||||
- GitHub Codespaces और VS Code dev कंटेनर समर्थन
|
||||
|
||||
## सेटअप कमांड्स
|
||||
|
||||
### रिपॉजिटरी सेटअप
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python एनवायरनमेंट सेटअप
|
||||
```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
|
||||
```
|
||||
|
||||
### क्विज़ एप्लिकेशन सेटअप
|
||||
```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 डॉक्यूमेंटेशन सर्वर
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### विज़ुअलाइज़ेशन प्रोजेक्ट्स सेटअप
|
||||
जैसे meaningful-visualizations (पाठ 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
|
||||
```
|
||||
|
||||
|
||||
## विकास कार्यप्रवाह
|
||||
|
||||
### Jupyter नोटबुक के साथ काम करना
|
||||
1. रिपॉजिटरी रूट में Jupyter शुरू करें: `jupyter notebook`
|
||||
2. इच्छित पाठ फ़ोल्डर पर जाएं
|
||||
3. `.ipynb` फ़ाइलें खोलें और अभ्यास करें
|
||||
4. नोटबुक्स में स्पष्टीकरण और कोड सेल्स होते हैं
|
||||
5. अधिकांश नोटबुक्स 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)
|
||||
|
||||
## परीक्षण निर्देश
|
||||
|
||||
### क्विज़ एप्लिकेशन परीक्षण
|
||||
```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
|
||||
```
|
||||
|
||||
### नोटबुक परीक्षण
|
||||
- नोटबुक्स के लिए कोई स्वचालित परीक्षण फ्रेमवर्क मौजूद नहीं है
|
||||
- मैन्युअल सत्यापन: सभी सेल्स को क्रम में चलाएं ताकि कोई त्रुटि न हो
|
||||
- सुनिश्चित करें कि डेटा फ़ाइलें सुलभ हैं और आउटपुट सही ढंग से उत्पन्न होते हैं
|
||||
- जांचें कि विज़ुअलाइज़ेशन सही ढंग से रेंडर होते हैं
|
||||
|
||||
### डॉक्यूमेंटेशन परीक्षण
|
||||
```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
|
||||
```
|
||||
|
||||
### कोड गुणवत्ता जांच
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## कोड शैली दिशानिर्देश
|
||||
|
||||
### Python (Jupyter नोटबुक्स)
|
||||
- Python कोड के लिए PEP 8 शैली दिशानिर्देशों का पालन करें
|
||||
- स्पष्ट वेरिएबल नामों का उपयोग करें जो विश्लेषण किए जा रहे डेटा को समझाएं
|
||||
- कोड सेल्स से पहले स्पष्टीकरण के साथ Markdown सेल्स शामिल करें
|
||||
- कोड सेल्स को एकल अवधारणाओं या संचालन पर केंद्रित रखें
|
||||
- डेटा हेरफेर के लिए pandas और विज़ुअलाइज़ेशन के लिए matplotlib का उपयोग करें
|
||||
- सामान्य आयात पैटर्न:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Vue.js 2 शैली गाइड और सर्वोत्तम प्रथाओं का पालन करें
|
||||
- ESLint कॉन्फ़िगरेशन `quiz-app/package.json` में
|
||||
- Vue सिंगल-फाइल घटकों (.vue फ़ाइलें) का उपयोग करें
|
||||
- घटक-आधारित आर्किटेक्चर बनाए रखें
|
||||
- परिवर्तन करने से पहले `npm run lint` चलाएं
|
||||
|
||||
### Markdown डॉक्यूमेंटेशन
|
||||
- स्पष्ट शीर्षक पदानुक्रम (# ## ### आदि) का उपयोग करें
|
||||
- भाषा निर्दिष्ट करने वाले कोड ब्लॉक शामिल करें
|
||||
- छवियों के लिए alt टेक्स्ट जोड़ें
|
||||
- संबंधित पाठ और संसाधनों के लिंक जोड़ें
|
||||
- पठनीयता के लिए लाइन लंबाई उचित रखें
|
||||
|
||||
### फ़ाइल संगठन
|
||||
- पाठ सामग्री क्रमांकित फ़ोल्डरों में (01-defining-data-science, आदि)
|
||||
- समाधान समर्पित `solution/` उपफ़ोल्डरों में
|
||||
- अनुवाद अंग्रेजी संरचना को `translations/` फ़ोल्डर में दर्शाते हैं
|
||||
- डेटा फ़ाइलें `data/` या पाठ-विशिष्ट फ़ोल्डरों में रखें
|
||||
|
||||
## निर्माण और परिनियोजन
|
||||
|
||||
### क्विज़ एप्लिकेशन परिनियोजन
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps परिनियोजन
|
||||
क्विज़-ऐप को Azure Static Web Apps पर परिनियोजित किया जा सकता है:
|
||||
1. Azure Static Web App संसाधन बनाएं
|
||||
2. GitHub रिपॉजिटरी से कनेक्ट करें
|
||||
3. निर्माण सेटिंग्स कॉन्फ़िगर करें:
|
||||
- ऐप स्थान: `quiz-app`
|
||||
- आउटपुट स्थान: `dist`
|
||||
4. GitHub Actions वर्कफ़्लो पुश पर स्वचालित रूप से परिनियोजित करेगा
|
||||
|
||||
### डॉक्यूमेंटेशन साइट
|
||||
```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
|
||||
- रिपॉजिटरी में dev कंटेनर कॉन्फ़िगरेशन शामिल है
|
||||
- Codespaces स्वचालित रूप से Python और Node.js एनवायरनमेंट सेट करता है
|
||||
- GitHub UI के माध्यम से रिपॉजिटरी को Codespace में खोलें
|
||||
- सभी निर्भरताएं स्वचालित रूप से इंस्टॉल होती हैं
|
||||
|
||||
## पुल अनुरोध दिशानिर्देश
|
||||
|
||||
### सबमिट करने से पहले
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR शीर्षक प्रारूप
|
||||
- स्पष्ट, वर्णनात्मक शीर्षक का उपयोग करें
|
||||
- प्रारूप: `[घटक] संक्षिप्त विवरण`
|
||||
- उदाहरण:
|
||||
- `[Lesson 7] Python नोटबुक आयात त्रुटि ठीक करें`
|
||||
- `[Quiz App] जर्मन अनुवाद जोड़ें`
|
||||
- `[Docs] README को नए आवश्यकताओं के साथ अपडेट करें`
|
||||
|
||||
### आवश्यक जांच
|
||||
- सुनिश्चित करें कि सभी कोड त्रुटियों के बिना चलते हैं
|
||||
- सत्यापित करें कि नोटबुक्स पूरी तरह से निष्पादित होते हैं
|
||||
- पुष्टि करें कि Vue.js ऐप्स सफलतापूर्वक बनते हैं
|
||||
- जांचें कि डॉक्यूमेंटेशन लिंक काम करते हैं
|
||||
- यदि संशोधित किया गया हो तो क्विज़ एप्लिकेशन का परीक्षण करें
|
||||
- सुनिश्चित करें कि अनुवाद संरचना सुसंगत बनाए रखते हैं
|
||||
|
||||
### योगदान दिशानिर्देश
|
||||
- मौजूदा कोड शैली और पैटर्न का पालन करें
|
||||
- जटिल तर्क के लिए व्याख्यात्मक टिप्पणियां जोड़ें
|
||||
- संबंधित डॉक्यूमेंटेशन अपडेट करें
|
||||
- यदि लागू हो तो विभिन्न पाठ मॉड्यूल में परिवर्तनों का परीक्षण करें
|
||||
- CONTRIBUTING.md फ़ाइल की समीक्षा करें
|
||||
|
||||
## अतिरिक्त नोट्स
|
||||
|
||||
### सामान्य उपयोग की जाने वाली लाइब्रेरीज़
|
||||
- **pandas**: डेटा हेरफेर और विश्लेषण
|
||||
- **numpy**: संख्यात्मक गणना
|
||||
- **matplotlib**: डेटा विज़ुअलाइज़ेशन और प्लॉटिंग
|
||||
- **seaborn**: सांख्यिकीय डेटा विज़ुअलाइज़ेशन (कुछ पाठ)
|
||||
- **scikit-learn**: मशीन लर्निंग (उन्नत पाठ)
|
||||
|
||||
### डेटा फ़ाइलों के साथ काम करना
|
||||
- डेटा फ़ाइलें `data/` फ़ोल्डर या पाठ-विशिष्ट निर्देशिकाओं में स्थित हैं
|
||||
- अधिकांश नोटबुक्स अपेक्षा करते हैं कि डेटा फ़ाइलें सापेक्ष पथों में हों
|
||||
- CSV फ़ाइलें प्राथमिक डेटा प्रारूप हैं
|
||||
- कुछ पाठ गैर-संबंधपरक डेटा उदाहरणों के लिए JSON का उपयोग करते हैं
|
||||
|
||||
### बहुभाषी समर्थन
|
||||
- स्वचालित GitHub Actions के माध्यम से 40+ भाषा अनुवाद
|
||||
- अनुवाद वर्कफ़्लो `.github/workflows/co-op-translator.yml` में
|
||||
- अनुवाद `translations/` फ़ोल्डर में भाषा कोड के साथ
|
||||
- क्विज़ अनुवाद `quiz-app/src/assets/translations/` में
|
||||
|
||||
### विकास पर्यावरण विकल्प
|
||||
1. **स्थानीय विकास**: Python, Jupyter, Node.js को स्थानीय रूप से इंस्टॉल करें
|
||||
2. **GitHub Codespaces**: क्लाउड-आधारित त्वरित विकास पर्यावरण
|
||||
3. **VS Code Dev Containers**: स्थानीय कंटेनर-आधारित विकास
|
||||
4. **Binder**: क्लाउड में नोटबुक्स लॉन्च करें (यदि कॉन्फ़िगर किया गया हो)
|
||||
|
||||
### पाठ सामग्री दिशानिर्देश
|
||||
- प्रत्येक पाठ स्वतंत्र है लेकिन पिछले अवधारणाओं पर आधारित है
|
||||
- प्री-पाठ क्विज़ पूर्व ज्ञान का परीक्षण करते हैं
|
||||
- पोस्ट-पाठ क्विज़ सीखने को सुदृढ़ करते हैं
|
||||
- असाइनमेंट व्यावहारिक अभ्यास प्रदान करते हैं
|
||||
- स्केच नोट्स दृश्य सारांश प्रदान करते हैं
|
||||
|
||||
### सामान्य समस्याओं का निवारण
|
||||
|
||||
**Jupyter कर्नेल समस्याएं:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm इंस्टॉल विफलताएं:**
|
||||
```bash
|
||||
# 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 dev सर्वर त्वरित पुनरावृत्ति के लिए हॉट-रिलोड सक्षम करता है
|
||||
- प्रोडक्शन बिल्ड्स अनुकूलित और मिनिफाइड होते हैं
|
||||
|
||||
### सुरक्षा नोट्स
|
||||
- कोई संवेदनशील डेटा या क्रेडेंशियल्स कमिट नहीं किए जाने चाहिए
|
||||
- क्लाउड पाठों में किसी भी 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 की समीक्षा
|
||||
- मासिक सामग्री समीक्षा और अपडेट
|
||||
|
||||
---
|
||||
|
||||
**अस्वीकरण**:
|
||||
यह दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके अनुवादित किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवाद में त्रुटियां या अशुद्धियां हो सकती हैं। मूल भाषा में उपलब्ध मूल दस्तावेज़ को आधिकारिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं।
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:42:38+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "hr"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Pregled projekta
|
||||
|
||||
Data Science for Beginners je sveobuhvatan 10-tjedni, 20-lekcijski kurikulum koji su kreirali Microsoft Azure Cloud Advocates. Repozitorij je edukativni resurs koji podučava osnovne koncepte podatkovne znanosti kroz lekcije temeljene na projektima, uključujući Jupyter bilježnice, interaktivne kvizove i praktične zadatke.
|
||||
|
||||
**Ključne tehnologije:**
|
||||
- **Jupyter bilježnice**: Glavni medij za učenje koristeći Python 3
|
||||
- **Python biblioteke**: pandas, numpy, matplotlib za analizu podataka i vizualizaciju
|
||||
- **Vue.js 2**: Aplikacija za kvizove (mapa quiz-app)
|
||||
- **Docsify**: Generator dokumentacijskih stranica za offline pristup
|
||||
- **Node.js/npm**: Upravljanje paketima za JavaScript komponente
|
||||
- **Markdown**: Sav sadržaj lekcija i dokumentacija
|
||||
|
||||
**Arhitektura:**
|
||||
- Edukativni repozitorij na više jezika s opsežnim prijevodima
|
||||
- Strukturiran u module lekcija (1-Uvod do 6-Podatkovna-Znanost-U-Praksi)
|
||||
- Svaka lekcija uključuje README, bilježnice, zadatke i kvizove
|
||||
- Samostalna Vue.js aplikacija za kvizove za procjenu prije/poslije lekcije
|
||||
- Podrška za GitHub Codespaces i VS Code razvojne kontejnere
|
||||
|
||||
## Postavljanje repozitorija
|
||||
|
||||
### Postavljanje repozitorija
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Postavljanje Python okruženja
|
||||
```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
|
||||
```
|
||||
|
||||
### Postavljanje aplikacije za kvizove
|
||||
```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 dokumentacijski server
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Postavljanje projekata za vizualizaciju
|
||||
Za projekte vizualizacije poput meaningful-visualizations (lekcija 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
|
||||
```
|
||||
|
||||
|
||||
## Radni tijek razvoja
|
||||
|
||||
### Rad s Jupyter bilježnicama
|
||||
1. Pokrenite Jupyter u korijenu repozitorija: `jupyter notebook`
|
||||
2. Navigirajte do željene mape lekcije
|
||||
3. Otvorite `.ipynb` datoteke za rad na vježbama
|
||||
4. Bilježnice su samostalne s objašnjenjima i kodnim ćelijama
|
||||
5. Većina bilježnica koristi pandas, numpy i matplotlib - osigurajte da su instalirani
|
||||
|
||||
### Struktura lekcije
|
||||
Svaka lekcija obično sadrži:
|
||||
- `README.md` - Glavni sadržaj lekcije s teorijom i primjerima
|
||||
- `notebook.ipynb` - Praktične vježbe u Jupyter bilježnici
|
||||
- `assignment.ipynb` ili `assignment.md` - Praktični zadaci
|
||||
- `solution/` mapa - Bilježnice s rješenjima i kod
|
||||
- `images/` mapa - Vizualni materijali za podršku
|
||||
|
||||
### Razvoj aplikacije za kvizove
|
||||
- Vue.js 2 aplikacija s hot-reload funkcijom tijekom razvoja
|
||||
- Kvizovi se nalaze u `quiz-app/src/assets/translations/`
|
||||
- Svaki jezik ima vlastitu mapu za prijevode (en, fr, es, itd.)
|
||||
- Numeracija kvizova počinje od 0 i ide do 39 (ukupno 40 kvizova)
|
||||
|
||||
### Dodavanje prijevoda
|
||||
- Prijevodi se nalaze u mapi `translations/` u korijenu repozitorija
|
||||
- Svaki jezik ima potpunu strukturu lekcija preslikanu iz engleskog
|
||||
- Automatski prijevod putem GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Upute za testiranje
|
||||
|
||||
### Testiranje aplikacije za kvizove
|
||||
```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
|
||||
```
|
||||
|
||||
### Testiranje bilježnica
|
||||
- Ne postoji automatizirani okvir za testiranje bilježnica
|
||||
- Ručna validacija: Pokrenite sve ćelije redom kako biste osigurali da nema grešaka
|
||||
- Provjerite dostupnost datoteka s podacima i generiranje izlaza
|
||||
- Provjerite ispravnost prikaza vizualizacija
|
||||
|
||||
### Testiranje dokumentacije
|
||||
```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
|
||||
```
|
||||
|
||||
### Provjere kvalitete koda
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Smjernice za stil koda
|
||||
|
||||
### Python (Jupyter bilježnice)
|
||||
- Slijedite PEP 8 smjernice za stil Python koda
|
||||
- Koristite jasne nazive varijabli koje objašnjavaju podatke koji se analiziraju
|
||||
- Dodajte markdown ćelije s objašnjenjima prije kodnih ćelija
|
||||
- Fokusirajte kodne ćelije na pojedinačne koncepte ili operacije
|
||||
- Koristite pandas za manipulaciju podacima, matplotlib za vizualizaciju
|
||||
- Uobičajeni uzorak uvoza:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Slijedite Vue.js 2 smjernice za stil i najbolje prakse
|
||||
- ESLint konfiguracija u `quiz-app/package.json`
|
||||
- Koristite Vue komponente u jednoj datoteci (.vue datoteke)
|
||||
- Održavajte arhitekturu temeljenu na komponentama
|
||||
- Pokrenite `npm run lint` prije predaje promjena
|
||||
|
||||
### Markdown dokumentacija
|
||||
- Koristite jasnu hijerarhiju naslova (# ## ### itd.)
|
||||
- Dodajte kodne blokove s oznakama jezika
|
||||
- Dodajte alt tekst za slike
|
||||
- Povežite se na povezane lekcije i resurse
|
||||
- Održavajte razumne duljine linija radi čitljivosti
|
||||
|
||||
### Organizacija datoteka
|
||||
- Sadržaj lekcija u numeriranim mapama (01-defining-data-science, itd.)
|
||||
- Rješenja u namjenskim `solution/` podmapama
|
||||
- Prijevodi preslikavaju englesku strukturu u mapi `translations/`
|
||||
- Datoteke s podacima u `data/` ili mapama specifičnim za lekcije
|
||||
|
||||
## Izgradnja i implementacija
|
||||
|
||||
### Implementacija aplikacije za kvizove
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Implementacija Azure Static Web Apps
|
||||
Aplikacija za kvizove može se implementirati na Azure Static Web Apps:
|
||||
1. Kreirajte resurs Azure Static Web App
|
||||
2. Povežite se s GitHub repozitorijem
|
||||
3. Konfigurirajte postavke izgradnje:
|
||||
- Lokacija aplikacije: `quiz-app`
|
||||
- Lokacija izlaza: `dist`
|
||||
4. GitHub Actions tijek rada automatski će implementirati promjene nakon guranja
|
||||
|
||||
### Dokumentacijska stranica
|
||||
```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
|
||||
- Repozitorij uključuje konfiguraciju razvojnih kontejnera
|
||||
- Codespaces automatski postavlja Python i Node.js okruženje
|
||||
- Otvorite repozitorij u Codespace putem GitHub sučelja
|
||||
- Sve ovisnosti se automatski instaliraju
|
||||
|
||||
## Smjernice za Pull Requestove
|
||||
|
||||
### Prije predaje
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format naslova PR-a
|
||||
- Koristite jasne, opisne naslove
|
||||
- Format: `[Komponenta] Kratak opis`
|
||||
- Primjeri:
|
||||
- `[Lekcija 7] Popravak greške uvoza u Python bilježnici`
|
||||
- `[Aplikacija za kvizove] Dodavanje njemačkog prijevoda`
|
||||
- `[Dokumentacija] Ažuriranje README s novim preduvjetima`
|
||||
|
||||
### Potrebne provjere
|
||||
- Osigurajte da se sav kod izvršava bez grešaka
|
||||
- Provjerite da se bilježnice potpuno izvršavaju
|
||||
- Potvrdite da se Vue.js aplikacije uspješno izgrađuju
|
||||
- Provjerite da veze u dokumentaciji rade
|
||||
- Testirajte aplikaciju za kvizove ako je izmijenjena
|
||||
- Provjerite da prijevodi održavaju dosljednu strukturu
|
||||
|
||||
### Smjernice za doprinos
|
||||
- Slijedite postojeći stil koda i uzorke
|
||||
- Dodajte objašnjavajuće komentare za složenu logiku
|
||||
- Ažurirajte relevantnu dokumentaciju
|
||||
- Testirajte promjene kroz različite module lekcija ako je primjenjivo
|
||||
- Pregledajte datoteku CONTRIBUTING.md
|
||||
|
||||
## Dodatne napomene
|
||||
|
||||
### Uobičajene korištene biblioteke
|
||||
- **pandas**: Manipulacija i analiza podataka
|
||||
- **numpy**: Numeričko računanje
|
||||
- **matplotlib**: Vizualizacija i crtanje podataka
|
||||
- **seaborn**: Statistička vizualizacija podataka (neke lekcije)
|
||||
- **scikit-learn**: Strojno učenje (napredne lekcije)
|
||||
|
||||
### Rad s datotekama podataka
|
||||
- Datoteke podataka nalaze se u mapi `data/` ili mapama specifičnim za lekcije
|
||||
- Većina bilježnica očekuje datoteke podataka u relativnim putanjama
|
||||
- CSV datoteke su primarni format podataka
|
||||
- Neke lekcije koriste JSON za primjere nerelacijskih podataka
|
||||
|
||||
### Podrška za više jezika
|
||||
- 40+ prijevoda jezika putem automatiziranih GitHub Actions
|
||||
- Tijek rada za prijevod u `.github/workflows/co-op-translator.yml`
|
||||
- Prijevodi u mapi `translations/` s kodovima jezika
|
||||
- Prijevodi kvizova u `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opcije razvojnih okruženja
|
||||
1. **Lokalni razvoj**: Instalirajte Python, Jupyter, Node.js lokalno
|
||||
2. **GitHub Codespaces**: Cloud-based instant razvojno okruženje
|
||||
3. **VS Code razvojni kontejneri**: Lokalni razvoj temeljen na kontejnerima
|
||||
4. **Binder**: Pokrenite bilježnice u oblaku (ako je konfigurirano)
|
||||
|
||||
### Smjernice za sadržaj lekcija
|
||||
- Svaka lekcija je samostalna, ali se nadovezuje na prethodne koncepte
|
||||
- Kvizovi prije lekcije testiraju prethodno znanje
|
||||
- Kvizovi nakon lekcije učvršćuju naučeno
|
||||
- Zadaci pružaju praktičnu vježbu
|
||||
- Sketchnotes pružaju vizualne sažetke
|
||||
|
||||
### Rješavanje uobičajenih problema
|
||||
|
||||
**Problemi s Jupyter kernelom:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Neuspjesi instalacije npm-a:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Greške uvoza u bilježnicama:**
|
||||
- Provjerite jesu li sve potrebne biblioteke instalirane
|
||||
- Provjerite kompatibilnost verzije Pythona (preporučuje se Python 3.7+)
|
||||
- Osigurajte da je virtualno okruženje aktivirano
|
||||
|
||||
**Docsify se ne učitava:**
|
||||
- Provjerite da poslužujete iz korijena repozitorija
|
||||
- Provjerite da `index.html` postoji
|
||||
- Osigurajte ispravan mrežni pristup (port 3000)
|
||||
|
||||
### Razmatranja performansi
|
||||
- Veliki skupovi podataka mogu zahtijevati vrijeme za učitavanje u bilježnicama
|
||||
- Prikaz vizualizacija može biti spor za složene grafikone
|
||||
- Vue.js razvojni server omogućuje hot-reload za brzu iteraciju
|
||||
- Produkcijske izgradnje su optimizirane i minimizirane
|
||||
|
||||
### Sigurnosne napomene
|
||||
- Ne smiju se predavati osjetljivi podaci ili vjerodajnice
|
||||
- Koristite varijable okruženja za API ključeve u lekcijama u oblaku
|
||||
- Lekcije povezane s Azureom mogu zahtijevati vjerodajnice za Azure račun
|
||||
- Održavajte ažuriranost ovisnosti radi sigurnosnih zakrpa
|
||||
|
||||
## Doprinos prijevodima
|
||||
- Automatski prijevodi upravljani putem GitHub Actions
|
||||
- Ručne korekcije dobrodošle za točnost prijevoda
|
||||
- Slijedite postojeću strukturu mapa za prijevode
|
||||
- Ažurirajte poveznice kvizova kako bi uključivale parametar jezika: `?loc=fr`
|
||||
- Testirajte prevedene lekcije za ispravan prikaz
|
||||
|
||||
## Povezani resursi
|
||||
- Glavni kurikulum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum za raspravu: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Ostali Microsoft kurikulumi: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Održavanje projekta
|
||||
- Redovita ažuriranja za održavanje aktualnosti sadržaja
|
||||
- Doprinosi zajednice su dobrodošli
|
||||
- Problemi se prate na GitHubu
|
||||
- PR-ove pregledavaju održavatelji kurikuluma
|
||||
- Mjesečni pregledi i ažuriranja sadržaja
|
||||
|
||||
---
|
||||
|
||||
**Izjava o odricanju odgovornosti**:
|
||||
Ovaj dokument je preveden pomoću AI usluge za prevođenje [Co-op Translator](https://github.com/Azure/co-op-translator). Iako nastojimo osigurati točnost, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za ključne informacije preporučuje se profesionalni prijevod od strane ljudskog prevoditelja. Ne preuzimamo odgovornost za nesporazume ili pogrešna tumačenja koja mogu proizaći iz korištenja ovog prijevoda.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:35:23+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "hu"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Projekt áttekintése
|
||||
|
||||
A Data Science for Beginners egy átfogó, 10 hetes, 20 leckéből álló tananyag, amelyet a Microsoft Azure Cloud Advocates készített. A repozitórium egy tanulási erőforrás, amely projektalapú leckéken keresztül tanítja az adatkutatás alapvető fogalmait, beleértve a Jupyter notebookokat, interaktív kvízeket és gyakorlati feladatokat.
|
||||
|
||||
**Kulcstechnológiák:**
|
||||
- **Jupyter Notebookok**: Elsődleges tanulási eszköz Python 3 használatával
|
||||
- **Python könyvtárak**: pandas, numpy, matplotlib az adatelemzéshez és vizualizációhoz
|
||||
- **Vue.js 2**: Kvíz alkalmazás (quiz-app mappa)
|
||||
- **Docsify**: Dokumentációs oldal generátor offline hozzáféréshez
|
||||
- **Node.js/npm**: JavaScript komponensek csomagkezelése
|
||||
- **Markdown**: Minden lecke tartalma és dokumentáció
|
||||
|
||||
**Architektúra:**
|
||||
- Többnyelvű oktatási repozitórium kiterjedt fordításokkal
|
||||
- Leckemodulokra strukturálva (1-Bevezetés-től 6-Adattudomány-a-gyakorlatban-ig)
|
||||
- Minden lecke tartalmaz README-t, notebookokat, feladatokat és kvízeket
|
||||
- Önálló Vue.js kvíz alkalmazás elő-/utólecke értékelésekhez
|
||||
- GitHub Codespaces és VS Code fejlesztői konténerek támogatása
|
||||
|
||||
## Beállítási parancsok
|
||||
|
||||
### Repozitórium beállítása
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python környezet beállítása
|
||||
```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
|
||||
```
|
||||
|
||||
### Kvíz alkalmazás beállítása
|
||||
```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 dokumentációs szerver
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Vizualizációs projektek beállítása
|
||||
Olyan vizualizációs projektekhez, mint a meaningful-visualizations (13. lecke):
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Fejlesztési munkafolyamat
|
||||
|
||||
### Jupyter Notebookok használata
|
||||
1. Indítsa el a Jupyter-t a repozitórium gyökerében: `jupyter notebook`
|
||||
2. Navigáljon a kívánt lecke mappájába
|
||||
3. Nyissa meg a `.ipynb` fájlokat a gyakorlatok elvégzéséhez
|
||||
4. A notebookok önállóak, magyarázatokat és kódcellákat tartalmaznak
|
||||
5. A legtöbb notebook pandas, numpy és matplotlib használatát igényli - győződjön meg róla, hogy ezek telepítve vannak
|
||||
|
||||
### Lecke struktúra
|
||||
Minden lecke általában tartalmaz:
|
||||
- `README.md` - Fő lecke tartalom elmélettel és példákkal
|
||||
- `notebook.ipynb` - Gyakorlati Jupyter notebook gyakorlatok
|
||||
- `assignment.ipynb` vagy `assignment.md` - Gyakorlati feladatok
|
||||
- `solution/` mappa - Megoldási notebookok és kód
|
||||
- `images/` mappa - Támogató vizuális anyagok
|
||||
|
||||
### Kvíz alkalmazás fejlesztése
|
||||
- Vue.js 2 alkalmazás hot-reload funkcióval fejlesztés közben
|
||||
- Kvízek tárolása a `quiz-app/src/assets/translations/` mappában
|
||||
- Minden nyelvnek saját fordítási mappája van (en, fr, es stb.)
|
||||
- A kvízek számozása 0-tól kezdődik és 39-ig tart (összesen 40 kvíz)
|
||||
|
||||
### Fordítások hozzáadása
|
||||
- Fordítások a repozitórium gyökerében lévő `translations/` mappába kerülnek
|
||||
- Minden nyelv teljes lecke struktúrája tükrözi az angolt
|
||||
- Automatikus fordítás GitHub Actions segítségével (co-op-translator.yml)
|
||||
|
||||
## Tesztelési utasítások
|
||||
|
||||
### Kvíz alkalmazás tesztelése
|
||||
```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
|
||||
```
|
||||
|
||||
### Notebook tesztelése
|
||||
- Nincs automatizált tesztkeretrendszer a notebookokhoz
|
||||
- Manuális ellenőrzés: Futtassa az összes cellát sorrendben, hogy megbizonyosodjon róla, nincs hiba
|
||||
- Ellenőrizze, hogy az adatfájlok elérhetők-e, és az eredmények helyesen generálódnak-e
|
||||
- Győződjön meg róla, hogy a vizualizációk megfelelően jelennek meg
|
||||
|
||||
### Dokumentáció tesztelése
|
||||
```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
|
||||
```
|
||||
|
||||
### Kódminőség ellenőrzések
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Kódstílus irányelvek
|
||||
|
||||
### Python (Jupyter Notebookok)
|
||||
- Kövesse a PEP 8 stílusirányelveket Python kódhoz
|
||||
- Használjon egyértelmű változóneveket, amelyek magyarázzák az elemzett adatokat
|
||||
- Tartalmazzon markdown cellákat magyarázatokkal a kódcellák előtt
|
||||
- Tartsa a kódcellákat egyetlen fogalomra vagy műveletre fókuszálva
|
||||
- Használja a pandas-t adatmanipulációhoz, matplotlib-et vizualizációhoz
|
||||
- Gyakori import minta:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Kövesse a Vue.js 2 stílusirányelveket és legjobb gyakorlatokat
|
||||
- ESLint konfiguráció a `quiz-app/package.json` fájlban
|
||||
- Használjon Vue egyfájlú komponenseket (.vue fájlok)
|
||||
- Tartsa meg a komponens-alapú architektúrát
|
||||
- Futtassa az `npm run lint` parancsot a változtatások elkötelezése előtt
|
||||
|
||||
### Markdown dokumentáció
|
||||
- Használjon egyértelmű címsor hierarchiát (# ## ### stb.)
|
||||
- Tartalmazzon kódrészleteket nyelvi specifikációval
|
||||
- Adjon meg alternatív szöveget a képekhez
|
||||
- Linkeljen kapcsolódó leckékre és erőforrásokra
|
||||
- Tartsa a sorhosszúságot olvasható szinten
|
||||
|
||||
### Fájlok szervezése
|
||||
- Lecke tartalom számozott mappákban (01-defining-data-science stb.)
|
||||
- Megoldások dedikált `solution/` almappákban
|
||||
- Fordítások tükrözik az angol struktúrát a `translations/` mappában
|
||||
- Adatfájlok a `data/` vagy lecke-specifikus mappákban
|
||||
|
||||
## Építés és telepítés
|
||||
|
||||
### Kvíz alkalmazás telepítése
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps telepítés
|
||||
A quiz-app telepíthető Azure Static Web Apps-re:
|
||||
1. Hozzon létre Azure Static Web App erőforrást
|
||||
2. Csatlakoztassa a GitHub repozitóriumhoz
|
||||
3. Konfigurálja az építési beállításokat:
|
||||
- Alkalmazás helye: `quiz-app`
|
||||
- Kimeneti hely: `dist`
|
||||
4. A GitHub Actions munkafolyamat automatikusan telepíti a push után
|
||||
|
||||
### Dokumentációs oldal
|
||||
```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
|
||||
- A repozitórium tartalmaz fejlesztői konténer konfigurációt
|
||||
- A Codespaces automatikusan beállítja a Python és Node.js környezetet
|
||||
- Nyissa meg a repozitóriumot Codespace-ben a GitHub UI segítségével
|
||||
- Minden függőség automatikusan települ
|
||||
|
||||
## Pull Request irányelvek
|
||||
|
||||
### Beküldés előtt
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR cím formátuma
|
||||
- Használjon egyértelmű, leíró címeket
|
||||
- Formátum: `[Komponens] Rövid leírás`
|
||||
- Példák:
|
||||
- `[7. lecke] Python notebook import hiba javítása`
|
||||
- `[Kvíz alkalmazás] Német fordítás hozzáadása`
|
||||
- `[Dokumentáció] README frissítése új előfeltételekkel`
|
||||
|
||||
### Szükséges ellenőrzések
|
||||
- Győződjön meg róla, hogy minden kód hiba nélkül fut
|
||||
- Ellenőrizze, hogy a notebookok teljesen végrehajtódnak
|
||||
- Győződjön meg róla, hogy a Vue.js alkalmazások sikeresen épülnek
|
||||
- Ellenőrizze, hogy a dokumentációs linkek működnek
|
||||
- Tesztelje a kvíz alkalmazást, ha módosítva lett
|
||||
- Ellenőrizze, hogy a fordítások következetes struktúrát tartanak
|
||||
|
||||
### Hozzájárulási irányelvek
|
||||
- Kövesse a meglévő kódstílust és mintákat
|
||||
- Adjon magyarázó megjegyzéseket a bonyolult logikához
|
||||
- Frissítse a releváns dokumentációt
|
||||
- Tesztelje a változtatásokat különböző leckemodulokon, ha alkalmazható
|
||||
- Tekintse át a CONTRIBUTING.md fájlt
|
||||
|
||||
## További megjegyzések
|
||||
|
||||
### Gyakran használt könyvtárak
|
||||
- **pandas**: Adatmanipuláció és elemzés
|
||||
- **numpy**: Numerikus számítások
|
||||
- **matplotlib**: Adatvizualizáció és grafikonok
|
||||
- **seaborn**: Statisztikai adatvizualizáció (néhány lecke)
|
||||
- **scikit-learn**: Gépi tanulás (haladó leckék)
|
||||
|
||||
### Adatfájlok kezelése
|
||||
- Adatfájlok a `data/` mappában vagy lecke-specifikus könyvtárakban találhatók
|
||||
- A legtöbb notebook relatív útvonalakon várja az adatfájlokat
|
||||
- A CSV fájlok az elsődleges adatformátum
|
||||
- Néhány lecke JSON-t használ nem relációs adatpéldákhoz
|
||||
|
||||
### Többnyelvű támogatás
|
||||
- 40+ nyelvi fordítás automatikus GitHub Actions segítségével
|
||||
- Fordítási munkafolyamat a `.github/workflows/co-op-translator.yml` fájlban
|
||||
- Fordítások a `translations/` mappában nyelvi kódokkal
|
||||
- Kvíz fordítások a `quiz-app/src/assets/translations/` mappában
|
||||
|
||||
### Fejlesztési környezet opciók
|
||||
1. **Helyi fejlesztés**: Telepítse a Python-t, Jupyter-t, Node.js-t helyben
|
||||
2. **GitHub Codespaces**: Felhőalapú azonnali fejlesztési környezet
|
||||
3. **VS Code Dev Containers**: Helyi konténer-alapú fejlesztés
|
||||
4. **Binder**: Notebookok indítása felhőben (ha konfigurálva van)
|
||||
|
||||
### Lecke tartalom irányelvek
|
||||
- Minden lecke önálló, de az előző fogalmakra épít
|
||||
- Előlecke kvízek tesztelik az előzetes tudást
|
||||
- Utólecke kvízek megerősítik a tanultakat
|
||||
- Feladatok gyakorlati tapasztalatot nyújtanak
|
||||
- Sketchnotes vizuális összefoglalókat biztosítanak
|
||||
|
||||
### Gyakori problémák elhárítása
|
||||
|
||||
**Jupyter kernel problémák:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm telepítési hibák:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Import hibák notebookokban:**
|
||||
- Ellenőrizze, hogy minden szükséges könyvtár telepítve van-e
|
||||
- Ellenőrizze a Python verzió kompatibilitását (Python 3.7+ ajánlott)
|
||||
- Győződjön meg róla, hogy a virtuális környezet aktiválva van
|
||||
|
||||
**Docsify nem töltődik be:**
|
||||
- Ellenőrizze, hogy a repozitórium gyökeréből szolgáltat-e
|
||||
- Ellenőrizze, hogy létezik-e `index.html`
|
||||
- Győződjön meg róla, hogy megfelelő hálózati hozzáférés van (3000-es port)
|
||||
|
||||
### Teljesítmény szempontok
|
||||
- Nagy adathalmazok betöltése időt vehet igénybe a notebookokban
|
||||
- Vizualizációk megjelenítése lassú lehet összetett grafikonok esetén
|
||||
- A Vue.js fejlesztői szerver hot-reload funkciót biztosít gyors iterációhoz
|
||||
- A produkciós build-ek optimalizáltak és minifikáltak
|
||||
|
||||
### Biztonsági megjegyzések
|
||||
- Ne kötelezzen el érzékeny adatokat vagy hitelesítő adatokat
|
||||
- Használjon környezeti változókat bármilyen API kulcshoz felhőleckékben
|
||||
- Azure-hoz kapcsolódó leckékhez Azure fiók hitelesítő adatok szükségesek lehetnek
|
||||
- Tartsa a függőségeket naprakészen a biztonsági javítások érdekében
|
||||
|
||||
## Hozzájárulás fordításokhoz
|
||||
- Automatikus fordítások kezelése GitHub Actions segítségével
|
||||
- Kézi korrekciók szívesen látottak a fordítás pontossága érdekében
|
||||
- Kövesse a meglévő fordítási mappa struktúrát
|
||||
- Frissítse a kvíz linkeket, hogy tartalmazzák a nyelvi paramétert: `?loc=fr`
|
||||
- Tesztelje a fordított leckéket a megfelelő megjelenítés érdekében
|
||||
|
||||
## Kapcsolódó erőforrások
|
||||
- Fő tananyag: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Vita fórum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Egyéb Microsoft tananyagok: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Projekt karbantartás
|
||||
- Rendszeres frissítések a tartalom naprakészen tartásához
|
||||
- Közösségi hozzájárulások szívesen látottak
|
||||
- Problémák nyomon követése GitHub-on
|
||||
- PR-eket a tananyag karbantartói felülvizsgálják
|
||||
- Havi tartalomellenőrzések és frissítések
|
||||
|
||||
---
|
||||
|
||||
**Felelősség kizárása**:
|
||||
Ez a dokumentum az [Co-op Translator](https://github.com/Azure/co-op-translator) AI fordítási szolgáltatás segítségével került lefordításra. Bár törekszünk a pontosságra, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az eredeti nyelvén tekintendő hiteles forrásnak. Kritikus információk esetén javasolt professzionális emberi fordítást igénybe venni. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely a fordítás használatából eredhet.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:30:52+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "id"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Gambaran Proyek
|
||||
|
||||
Data Science for Beginners adalah kurikulum komprehensif selama 10 minggu dengan 20 pelajaran yang dibuat oleh Microsoft Azure Cloud Advocates. Repositori ini merupakan sumber pembelajaran yang mengajarkan konsep dasar ilmu data melalui pelajaran berbasis proyek, termasuk notebook Jupyter, kuis interaktif, dan tugas praktis.
|
||||
|
||||
**Teknologi Utama:**
|
||||
- **Jupyter Notebooks**: Media pembelajaran utama menggunakan Python 3
|
||||
- **Library Python**: pandas, numpy, matplotlib untuk analisis dan visualisasi data
|
||||
- **Vue.js 2**: Aplikasi kuis (folder quiz-app)
|
||||
- **Docsify**: Generator situs dokumentasi untuk akses offline
|
||||
- **Node.js/npm**: Manajemen paket untuk komponen JavaScript
|
||||
- **Markdown**: Semua konten pelajaran dan dokumentasi
|
||||
|
||||
**Arsitektur:**
|
||||
- Repositori edukasi multi-bahasa dengan terjemahan yang luas
|
||||
- Terstruktur dalam modul pelajaran (1-Introduction hingga 6-Data-Science-In-Wild)
|
||||
- Setiap pelajaran mencakup README, notebook, tugas, dan kuis
|
||||
- Aplikasi kuis Vue.js yang berdiri sendiri untuk penilaian sebelum/sesudah pelajaran
|
||||
- Dukungan GitHub Codespaces dan kontainer pengembangan VS Code
|
||||
|
||||
## Perintah Pengaturan
|
||||
|
||||
### Pengaturan Repositori
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Pengaturan Lingkungan Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Pengaturan Aplikasi Kuis
|
||||
```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
|
||||
```
|
||||
|
||||
### Server Dokumentasi Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Pengaturan Proyek Visualisasi
|
||||
Untuk proyek visualisasi seperti meaningful-visualizations (pelajaran 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
|
||||
```
|
||||
|
||||
|
||||
## Alur Kerja Pengembangan
|
||||
|
||||
### Bekerja dengan Jupyter Notebooks
|
||||
1. Mulai Jupyter di root repositori: `jupyter notebook`
|
||||
2. Navigasikan ke folder pelajaran yang diinginkan
|
||||
3. Buka file `.ipynb` untuk mengerjakan latihan
|
||||
4. Notebook bersifat mandiri dengan penjelasan dan sel kode
|
||||
5. Sebagian besar notebook menggunakan pandas, numpy, dan matplotlib - pastikan ini terinstal
|
||||
|
||||
### Struktur Pelajaran
|
||||
Setiap pelajaran biasanya mencakup:
|
||||
- `README.md` - Konten utama pelajaran dengan teori dan contoh
|
||||
- `notebook.ipynb` - Latihan praktis menggunakan Jupyter notebook
|
||||
- `assignment.ipynb` atau `assignment.md` - Tugas latihan
|
||||
- Folder `solution/` - Notebook solusi dan kode
|
||||
- Folder `images/` - Materi visual pendukung
|
||||
|
||||
### Pengembangan Aplikasi Kuis
|
||||
- Aplikasi Vue.js 2 dengan hot-reload selama pengembangan
|
||||
- Kuis disimpan di `quiz-app/src/assets/translations/`
|
||||
- Setiap bahasa memiliki folder terjemahan sendiri (en, fr, es, dll.)
|
||||
- Penomoran kuis dimulai dari 0 hingga 39 (total 40 kuis)
|
||||
|
||||
### Menambahkan Terjemahan
|
||||
- Terjemahan ditempatkan di folder `translations/` di root repositori
|
||||
- Setiap bahasa memiliki struktur pelajaran lengkap yang mencerminkan bahasa Inggris
|
||||
- Terjemahan otomatis melalui GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instruksi Pengujian
|
||||
|
||||
### Pengujian Aplikasi Kuis
|
||||
```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
|
||||
```
|
||||
|
||||
### Pengujian Notebook
|
||||
- Tidak ada kerangka pengujian otomatis untuk notebook
|
||||
- Validasi manual: Jalankan semua sel secara berurutan untuk memastikan tidak ada kesalahan
|
||||
- Verifikasi file data dapat diakses dan output dihasilkan dengan benar
|
||||
- Periksa apakah visualisasi ditampilkan dengan baik
|
||||
|
||||
### Pengujian Dokumentasi
|
||||
```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
|
||||
```
|
||||
|
||||
### Pemeriksaan Kualitas Kode
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Panduan Gaya Kode
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Ikuti panduan gaya PEP 8 untuk kode Python
|
||||
- Gunakan nama variabel yang jelas yang menjelaskan data yang dianalisis
|
||||
- Sertakan sel markdown dengan penjelasan sebelum sel kode
|
||||
- Fokuskan sel kode pada konsep atau operasi tunggal
|
||||
- Gunakan pandas untuk manipulasi data, matplotlib untuk visualisasi
|
||||
- Pola impor umum:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Ikuti panduan gaya Vue.js 2 dan praktik terbaik
|
||||
- Konfigurasi ESLint di `quiz-app/package.json`
|
||||
- Gunakan komponen Vue single-file (.vue files)
|
||||
- Pertahankan arsitektur berbasis komponen
|
||||
- Jalankan `npm run lint` sebelum melakukan commit
|
||||
|
||||
### Dokumentasi Markdown
|
||||
- Gunakan hierarki heading yang jelas (# ## ### dll.)
|
||||
- Sertakan blok kode dengan spesifikasi bahasa
|
||||
- Tambahkan teks alt untuk gambar
|
||||
- Tautkan ke pelajaran dan sumber daya terkait
|
||||
- Pertahankan panjang baris yang wajar untuk keterbacaan
|
||||
|
||||
### Organisasi File
|
||||
- Konten pelajaran dalam folder bernomor (01-defining-data-science, dll.)
|
||||
- Solusi dalam subfolder `solution/` khusus
|
||||
- Terjemahan mencerminkan struktur bahasa Inggris di folder `translations/`
|
||||
- Simpan file data di folder `data/` atau folder khusus pelajaran
|
||||
|
||||
## Build dan Deployment
|
||||
|
||||
### Deployment Aplikasi Kuis
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Deployment Azure Static Web Apps
|
||||
Aplikasi kuis dapat dideploy ke Azure Static Web Apps:
|
||||
1. Buat sumber daya Azure Static Web App
|
||||
2. Hubungkan ke repositori GitHub
|
||||
3. Konfigurasikan pengaturan build:
|
||||
- Lokasi aplikasi: `quiz-app`
|
||||
- Lokasi output: `dist`
|
||||
4. Workflow GitHub Actions akan otomatis mendeply saat ada push
|
||||
|
||||
### Situs Dokumentasi
|
||||
```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
|
||||
- Repositori mencakup konfigurasi kontainer pengembangan
|
||||
- Codespaces secara otomatis mengatur lingkungan Python dan Node.js
|
||||
- Buka repositori di Codespace melalui UI GitHub
|
||||
- Semua dependensi terinstal secara otomatis
|
||||
|
||||
## Panduan Pull Request
|
||||
|
||||
### Sebelum Mengirimkan
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format Judul PR
|
||||
- Gunakan judul yang jelas dan deskriptif
|
||||
- Format: `[Komponen] Deskripsi singkat`
|
||||
- Contoh:
|
||||
- `[Pelajaran 7] Perbaiki kesalahan impor notebook Python`
|
||||
- `[Aplikasi Kuis] Tambahkan terjemahan bahasa Jerman`
|
||||
- `[Dokumentasi] Perbarui README dengan prasyarat baru`
|
||||
|
||||
### Pemeriksaan yang Diperlukan
|
||||
- Pastikan semua kode berjalan tanpa kesalahan
|
||||
- Verifikasi notebook dieksekusi sepenuhnya
|
||||
- Konfirmasi aplikasi Vue.js berhasil dibangun
|
||||
- Periksa tautan dokumentasi berfungsi
|
||||
- Uji aplikasi kuis jika dimodifikasi
|
||||
- Verifikasi terjemahan mempertahankan struktur yang konsisten
|
||||
|
||||
### Panduan Kontribusi
|
||||
- Ikuti gaya dan pola kode yang ada
|
||||
- Tambahkan komentar penjelasan untuk logika yang kompleks
|
||||
- Perbarui dokumentasi yang relevan
|
||||
- Uji perubahan di berbagai modul pelajaran jika berlaku
|
||||
- Tinjau file CONTRIBUTING.md
|
||||
|
||||
## Catatan Tambahan
|
||||
|
||||
### Library Umum yang Digunakan
|
||||
- **pandas**: Manipulasi dan analisis data
|
||||
- **numpy**: Komputasi numerik
|
||||
- **matplotlib**: Visualisasi dan plotting data
|
||||
- **seaborn**: Visualisasi data statistik (beberapa pelajaran)
|
||||
- **scikit-learn**: Pembelajaran mesin (pelajaran lanjutan)
|
||||
|
||||
### Bekerja dengan File Data
|
||||
- File data terletak di folder `data/` atau direktori khusus pelajaran
|
||||
- Sebagian besar notebook mengharapkan file data di jalur relatif
|
||||
- File CSV adalah format data utama
|
||||
- Beberapa pelajaran menggunakan JSON untuk contoh data non-relasional
|
||||
|
||||
### Dukungan Multibahasa
|
||||
- Terjemahan lebih dari 40 bahasa melalui GitHub Actions otomatis
|
||||
- Workflow terjemahan di `.github/workflows/co-op-translator.yml`
|
||||
- Terjemahan di folder `translations/` dengan kode bahasa
|
||||
- Terjemahan kuis di `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opsi Lingkungan Pengembangan
|
||||
1. **Pengembangan Lokal**: Instal Python, Jupyter, Node.js secara lokal
|
||||
2. **GitHub Codespaces**: Lingkungan pengembangan instan berbasis cloud
|
||||
3. **VS Code Dev Containers**: Pengembangan berbasis kontainer lokal
|
||||
4. **Binder**: Luncurkan notebook di cloud (jika dikonfigurasi)
|
||||
|
||||
### Panduan Konten Pelajaran
|
||||
- Setiap pelajaran bersifat mandiri tetapi membangun konsep sebelumnya
|
||||
- Kuis sebelum pelajaran menguji pengetahuan awal
|
||||
- Kuis setelah pelajaran memperkuat pembelajaran
|
||||
- Tugas memberikan latihan praktis
|
||||
- Sketchnotes memberikan ringkasan visual
|
||||
|
||||
### Pemecahan Masalah Umum
|
||||
|
||||
**Masalah Kernel Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Kegagalan Instalasi npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Kesalahan Impor di Notebook:**
|
||||
- Verifikasi semua library yang diperlukan telah terinstal
|
||||
- Periksa kompatibilitas versi Python (disarankan Python 3.7+)
|
||||
- Pastikan lingkungan virtual diaktifkan
|
||||
|
||||
**Docsify Tidak Memuat:**
|
||||
- Verifikasi Anda melayani dari root repositori
|
||||
- Periksa bahwa `index.html` ada
|
||||
- Pastikan akses jaringan yang tepat (port 3000)
|
||||
|
||||
### Pertimbangan Performa
|
||||
- Dataset besar mungkin membutuhkan waktu untuk dimuat di notebook
|
||||
- Rendering visualisasi bisa lambat untuk plot yang kompleks
|
||||
- Server dev Vue.js memungkinkan hot-reload untuk iterasi cepat
|
||||
- Build produksi dioptimalkan dan diminimalkan
|
||||
|
||||
### Catatan Keamanan
|
||||
- Jangan komit data sensitif atau kredensial
|
||||
- Gunakan variabel lingkungan untuk kunci API dalam pelajaran cloud
|
||||
- Pelajaran terkait Azure mungkin memerlukan kredensial akun Azure
|
||||
- Pertahankan dependensi tetap diperbarui untuk patch keamanan
|
||||
|
||||
## Kontribusi untuk Terjemahan
|
||||
- Terjemahan otomatis dikelola melalui GitHub Actions
|
||||
- Koreksi manual diterima untuk akurasi terjemahan
|
||||
- Ikuti struktur folder terjemahan yang ada
|
||||
- Perbarui tautan kuis untuk menyertakan parameter bahasa: `?loc=fr`
|
||||
- Uji pelajaran yang diterjemahkan untuk memastikan tampilan yang benar
|
||||
|
||||
## Sumber Daya Terkait
|
||||
- Kurikulum utama: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum Diskusi: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Kurikulum Microsoft lainnya: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Pemeliharaan Proyek
|
||||
- Pembaruan rutin untuk menjaga konten tetap relevan
|
||||
- Kontribusi komunitas diterima
|
||||
- Masalah dilacak di GitHub
|
||||
- PR ditinjau oleh pemelihara kurikulum
|
||||
- Tinjauan dan pembaruan konten bulanan
|
||||
|
||||
---
|
||||
|
||||
**Penafian**:
|
||||
Dokumen ini telah diterjemahkan menggunakan layanan penerjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk memberikan hasil yang akurat, harap diperhatikan bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang otoritatif. Untuk informasi yang bersifat kritis, disarankan menggunakan jasa penerjemahan manusia profesional. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:18:00+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "it"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Panoramica del Progetto
|
||||
|
||||
Data Science for Beginners è un curriculum completo di 10 settimane e 20 lezioni creato dai Microsoft Azure Cloud Advocates. Il repository è una risorsa didattica che insegna i concetti fondamentali della data science attraverso lezioni basate su progetti, inclusi Jupyter notebook, quiz interattivi e compiti pratici.
|
||||
|
||||
**Tecnologie Chiave:**
|
||||
- **Jupyter Notebooks**: Principale mezzo di apprendimento utilizzando Python 3
|
||||
- **Librerie Python**: pandas, numpy, matplotlib per analisi e visualizzazione dei dati
|
||||
- **Vue.js 2**: Applicazione per quiz (cartella quiz-app)
|
||||
- **Docsify**: Generatore di siti di documentazione per accesso offline
|
||||
- **Node.js/npm**: Gestione dei pacchetti per componenti JavaScript
|
||||
- **Markdown**: Tutti i contenuti delle lezioni e la documentazione
|
||||
|
||||
**Architettura:**
|
||||
- Repository educativo multilingue con ampie traduzioni
|
||||
- Strutturato in moduli di lezione (1-Introduzione fino a 6-Data-Science-In-Wild)
|
||||
- Ogni lezione include README, notebook, compiti e quiz
|
||||
- Applicazione per quiz Vue.js autonoma per valutazioni pre/post lezione
|
||||
- Supporto per GitHub Codespaces e contenitori di sviluppo VS Code
|
||||
|
||||
## Comandi di Configurazione
|
||||
|
||||
### Configurazione del Repository
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Configurazione dell'Ambiente Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Configurazione dell'Applicazione per Quiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Server di Documentazione Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Configurazione dei Progetti di Visualizzazione
|
||||
Per progetti di visualizzazione come meaningful-visualizations (lezione 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
|
||||
```
|
||||
|
||||
|
||||
## Flusso di Lavoro per lo Sviluppo
|
||||
|
||||
### Lavorare con i Jupyter Notebooks
|
||||
1. Avvia Jupyter nella radice del repository: `jupyter notebook`
|
||||
2. Naviga nella cartella della lezione desiderata
|
||||
3. Apri i file `.ipynb` per lavorare sugli esercizi
|
||||
4. I notebook sono autonomi con spiegazioni e celle di codice
|
||||
5. La maggior parte dei notebook utilizza pandas, numpy e matplotlib - assicurati che siano installati
|
||||
|
||||
### Struttura delle Lezioni
|
||||
Ogni lezione contiene tipicamente:
|
||||
- `README.md` - Contenuto principale della lezione con teoria ed esempi
|
||||
- `notebook.ipynb` - Esercizi pratici con Jupyter notebook
|
||||
- `assignment.ipynb` o `assignment.md` - Compiti pratici
|
||||
- Cartella `solution/` - Notebook e codice delle soluzioni
|
||||
- Cartella `images/` - Materiali visivi di supporto
|
||||
|
||||
### Sviluppo dell'Applicazione per Quiz
|
||||
- Applicazione Vue.js 2 con hot-reload durante lo sviluppo
|
||||
- Quiz archiviati in `quiz-app/src/assets/translations/`
|
||||
- Ogni lingua ha la propria cartella di traduzione (en, fr, es, ecc.)
|
||||
- La numerazione dei quiz parte da 0 e arriva fino a 39 (40 quiz in totale)
|
||||
|
||||
### Aggiungere Traduzioni
|
||||
- Le traduzioni vanno nella cartella `translations/` alla radice del repository
|
||||
- Ogni lingua ha una struttura completa delle lezioni speculare a quella in inglese
|
||||
- Traduzione automatizzata tramite GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Istruzioni per i Test
|
||||
|
||||
### Test dell'Applicazione per Quiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Test dei Notebook
|
||||
- Non esiste un framework di test automatizzato per i notebook
|
||||
- Validazione manuale: Esegui tutte le celle in sequenza per assicurarti che non ci siano errori
|
||||
- Verifica che i file di dati siano accessibili e che gli output vengano generati correttamente
|
||||
- Controlla che le visualizzazioni vengano renderizzate correttamente
|
||||
|
||||
### Test della Documentazione
|
||||
```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
|
||||
```
|
||||
|
||||
### Controlli di Qualità del Codice
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Linee Guida per lo Stile del Codice
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Segui le linee guida di stile PEP 8 per il codice Python
|
||||
- Usa nomi di variabili chiari che spieghino i dati analizzati
|
||||
- Includi celle markdown con spiegazioni prima delle celle di codice
|
||||
- Mantieni le celle di codice focalizzate su concetti o operazioni singole
|
||||
- Usa pandas per la manipolazione dei dati, matplotlib per la visualizzazione
|
||||
- Modello comune di importazione:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Segui la guida di stile Vue.js 2 e le migliori pratiche
|
||||
- Configurazione ESLint in `quiz-app/package.json`
|
||||
- Usa componenti Vue a file singolo (.vue files)
|
||||
- Mantieni un'architettura basata sui componenti
|
||||
- Esegui `npm run lint` prima di inviare modifiche
|
||||
|
||||
### Documentazione Markdown
|
||||
- Usa una gerarchia chiara di intestazioni (# ## ### ecc.)
|
||||
- Includi blocchi di codice con specificatori di linguaggio
|
||||
- Aggiungi testo alternativo per le immagini
|
||||
- Collega lezioni e risorse correlate
|
||||
- Mantieni lunghezze di riga ragionevoli per la leggibilità
|
||||
|
||||
### Organizzazione dei File
|
||||
- Contenuti delle lezioni in cartelle numerate (01-defining-data-science, ecc.)
|
||||
- Soluzioni in sottocartelle dedicate `solution/`
|
||||
- Le traduzioni rispecchiano la struttura inglese nella cartella `translations/`
|
||||
- Mantieni i file di dati in `data/` o cartelle specifiche per le lezioni
|
||||
|
||||
## Build e Deployment
|
||||
|
||||
### Deployment dell'Applicazione per Quiz
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Deployment di Azure Static Web Apps
|
||||
L'app quiz può essere distribuita su Azure Static Web Apps:
|
||||
1. Crea una risorsa Azure Static Web App
|
||||
2. Connetti al repository GitHub
|
||||
3. Configura le impostazioni di build:
|
||||
- Posizione dell'app: `quiz-app`
|
||||
- Posizione dell'output: `dist`
|
||||
4. Il workflow GitHub Actions distribuirà automaticamente al push
|
||||
|
||||
### Sito di Documentazione
|
||||
```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
|
||||
- Il repository include configurazione del contenitore di sviluppo
|
||||
- Codespaces configura automaticamente l'ambiente Python e Node.js
|
||||
- Apri il repository in Codespace tramite l'interfaccia GitHub
|
||||
- Tutte le dipendenze vengono installate automaticamente
|
||||
|
||||
## Linee Guida per le Pull Request
|
||||
|
||||
### Prima di Inviare
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Formato del Titolo della PR
|
||||
- Usa titoli chiari e descrittivi
|
||||
- Formato: `[Componente] Breve descrizione`
|
||||
- Esempi:
|
||||
- `[Lezione 7] Correggi errore di importazione nel notebook Python`
|
||||
- `[Applicazione Quiz] Aggiungi traduzione in tedesco`
|
||||
- `[Documentazione] Aggiorna README con nuovi prerequisiti`
|
||||
|
||||
### Controlli Richiesti
|
||||
- Assicurati che tutto il codice venga eseguito senza errori
|
||||
- Verifica che i notebook vengano eseguiti completamente
|
||||
- Conferma che le app Vue.js vengano compilate con successo
|
||||
- Controlla che i link della documentazione funzionino
|
||||
- Testa l'app quiz se modificata
|
||||
- Verifica che le traduzioni mantengano una struttura coerente
|
||||
|
||||
### Linee Guida per il Contributo
|
||||
- Segui lo stile e i modelli di codice esistenti
|
||||
- Aggiungi commenti esplicativi per logiche complesse
|
||||
- Aggiorna la documentazione pertinente
|
||||
- Testa le modifiche su diversi moduli di lezione, se applicabile
|
||||
- Consulta il file CONTRIBUTING.md
|
||||
|
||||
## Note Aggiuntive
|
||||
|
||||
### Librerie Comuni Utilizzate
|
||||
- **pandas**: Manipolazione e analisi dei dati
|
||||
- **numpy**: Calcolo numerico
|
||||
- **matplotlib**: Visualizzazione e grafici dei dati
|
||||
- **seaborn**: Visualizzazione statistica dei dati (alcune lezioni)
|
||||
- **scikit-learn**: Machine learning (lezioni avanzate)
|
||||
|
||||
### Lavorare con i File di Dati
|
||||
- File di dati situati nella cartella `data/` o nelle directory specifiche delle lezioni
|
||||
- La maggior parte dei notebook si aspetta file di dati in percorsi relativi
|
||||
- I file CSV sono il formato principale dei dati
|
||||
- Alcune lezioni utilizzano JSON per esempi di dati non relazionali
|
||||
|
||||
### Supporto Multilingue
|
||||
- Traduzioni in oltre 40 lingue tramite GitHub Actions automatizzati
|
||||
- Workflow di traduzione in `.github/workflows/co-op-translator.yml`
|
||||
- Traduzioni nella cartella `translations/` con codici lingua
|
||||
- Traduzioni dei quiz in `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opzioni per l'Ambiente di Sviluppo
|
||||
1. **Sviluppo Locale**: Installa Python, Jupyter, Node.js localmente
|
||||
2. **GitHub Codespaces**: Ambiente di sviluppo istantaneo basato su cloud
|
||||
3. **Contenitori Dev di VS Code**: Sviluppo locale basato su contenitori
|
||||
4. **Binder**: Avvia notebook nel cloud (se configurato)
|
||||
|
||||
### Linee Guida per i Contenuti delle Lezioni
|
||||
- Ogni lezione è autonoma ma si basa su concetti precedenti
|
||||
- I quiz pre-lezione testano le conoscenze pregresse
|
||||
- I quiz post-lezione rafforzano l'apprendimento
|
||||
- I compiti forniscono pratica pratica
|
||||
- Gli sketchnotes offrono riassunti visivi
|
||||
|
||||
### Risoluzione dei Problemi Comuni
|
||||
|
||||
**Problemi con il Kernel di Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Errori di Installazione npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Errori di Importazione nei Notebook:**
|
||||
- Verifica che tutte le librerie richieste siano installate
|
||||
- Controlla la compatibilità della versione di Python (consigliato Python 3.7+)
|
||||
- Assicurati che l'ambiente virtuale sia attivato
|
||||
|
||||
**Docsify Non Carica:**
|
||||
- Verifica che stai servendo dalla radice del repository
|
||||
- Controlla che `index.html` esista
|
||||
- Assicurati di avere accesso alla rete corretta (porta 3000)
|
||||
|
||||
### Considerazioni sulle Prestazioni
|
||||
- I dataset di grandi dimensioni potrebbero richiedere tempo per il caricamento nei notebook
|
||||
- Il rendering delle visualizzazioni può essere lento per grafici complessi
|
||||
- Il server di sviluppo Vue.js abilita l'hot-reload per iterazioni rapide
|
||||
- Le build di produzione sono ottimizzate e minificate
|
||||
|
||||
### Note sulla Sicurezza
|
||||
- Non devono essere commessi dati sensibili o credenziali
|
||||
- Usa variabili d'ambiente per eventuali chiavi API nelle lezioni cloud
|
||||
- Le lezioni relative ad Azure potrebbero richiedere credenziali dell'account Azure
|
||||
- Mantieni le dipendenze aggiornate per le patch di sicurezza
|
||||
|
||||
## Contribuire alle Traduzioni
|
||||
- Le traduzioni automatizzate sono gestite tramite GitHub Actions
|
||||
- Correzioni manuali sono benvenute per migliorare l'accuratezza delle traduzioni
|
||||
- Segui la struttura esistente delle cartelle di traduzione
|
||||
- Aggiorna i link dei quiz per includere il parametro della lingua: `?loc=fr`
|
||||
- Testa le lezioni tradotte per verificarne il corretto rendering
|
||||
|
||||
## Risorse Correlate
|
||||
- Curriculum principale: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum di discussione: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Altri curricula Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Manutenzione del Progetto
|
||||
- Aggiornamenti regolari per mantenere i contenuti attuali
|
||||
- Contributi della comunità benvenuti
|
||||
- Problemi tracciati su GitHub
|
||||
- PR revisionate dai manutentori del curriculum
|
||||
- Revisioni e aggiornamenti mensili dei contenuti
|
||||
|
||||
---
|
||||
|
||||
**Disclaimer**:
|
||||
Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire l'accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa dovrebbe essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un traduttore umano. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall'uso di questa traduzione.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:10:09+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "ko"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## 프로젝트 개요
|
||||
|
||||
Data Science for Beginners는 Microsoft Azure Cloud Advocates가 제작한 10주, 20강의 종합 커리큘럼입니다. 이 저장소는 Jupyter 노트북, 인터랙티브 퀴즈, 실습 과제를 포함한 프로젝트 기반 강의를 통해 데이터 과학의 기초 개념을 가르치는 학습 자료입니다.
|
||||
|
||||
**주요 기술:**
|
||||
- **Jupyter 노트북**: 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 개발 컨테이너 지원
|
||||
|
||||
## 설정 명령어
|
||||
|
||||
### 저장소 설정
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python 환경 설정
|
||||
```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
|
||||
```
|
||||
|
||||
### 퀴즈 애플리케이션 설정
|
||||
```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 문서 서버
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### 시각화 프로젝트 설정
|
||||
예: meaningful-visualizations (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
|
||||
```
|
||||
|
||||
|
||||
## 개발 워크플로우
|
||||
|
||||
### Jupyter 노트북 작업
|
||||
1. 저장소 루트에서 Jupyter 시작: `jupyter notebook`
|
||||
2. 원하는 강의 폴더로 이동
|
||||
3. `.ipynb` 파일 열어 연습 진행
|
||||
4. 노트북은 설명과 코드 셀이 포함된 독립형 자료
|
||||
5. 대부분의 노트북은 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부터 시작하여 총 40개
|
||||
|
||||
### 번역 추가
|
||||
- 번역은 저장소 루트의 `translations/` 폴더에 저장
|
||||
- 각 언어는 영어 구조를 그대로 따름
|
||||
- GitHub Actions를 통한 자동 번역 (co-op-translator.yml)
|
||||
|
||||
## 테스트 지침
|
||||
|
||||
### 퀴즈 애플리케이션 테스트
|
||||
```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
|
||||
```
|
||||
|
||||
### 노트북 테스트
|
||||
- 노트북에 대한 자동화된 테스트 프레임워크는 없음
|
||||
- 수동 검증: 모든 셀을 순서대로 실행하여 오류 없는지 확인
|
||||
- 데이터 파일 접근 가능 여부 및 출력 생성 확인
|
||||
- 시각화가 올바르게 렌더링되는지 확인
|
||||
|
||||
### 문서 테스트
|
||||
```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
|
||||
```
|
||||
|
||||
### 코드 품질 검사
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## 코드 스타일 지침
|
||||
|
||||
### Python (Jupyter 노트북)
|
||||
- Python 코드에 대해 PEP 8 스타일 지침 준수
|
||||
- 분석 중인 데이터를 설명하는 명확한 변수명 사용
|
||||
- 코드 셀 앞에 설명이 포함된 Markdown 셀 추가
|
||||
- 코드 셀은 단일 개념 또는 작업에 집중
|
||||
- 데이터 조작에는 pandas, 시각화에는 matplotlib 사용
|
||||
- 일반적인 import 패턴:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Vue.js 2 스타일 가이드 및 모범 사례 준수
|
||||
- `quiz-app/package.json`에 ESLint 구성
|
||||
- Vue 단일 파일 구성 요소 (.vue 파일) 사용
|
||||
- 컴포넌트 기반 아키텍처 유지
|
||||
- 변경 사항 커밋 전에 `npm run lint` 실행
|
||||
|
||||
### Markdown 문서화
|
||||
- 명확한 제목 계층 구조 사용 (# ## ### 등)
|
||||
- 언어 지정자를 포함한 코드 블록 추가
|
||||
- 이미지에 alt 텍스트 추가
|
||||
- 관련 강의 및 리소스 링크 추가
|
||||
- 가독성을 위해 적절한 줄 길이 유지
|
||||
|
||||
### 파일 구성
|
||||
- 번호가 매겨진 폴더에 강의 내용 저장 (01-defining-data-science 등)
|
||||
- 솔루션은 전용 `solution/` 하위 폴더에 저장
|
||||
- 번역은 영어 구조를 그대로 따르는 `translations/` 폴더에 저장
|
||||
- 데이터 파일은 `data/` 또는 강의별 폴더에 저장
|
||||
|
||||
## 빌드 및 배포
|
||||
|
||||
### 퀴즈 애플리케이션 배포
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps 배포
|
||||
퀴즈 애플리케이션은 Azure Static Web Apps에 배포 가능:
|
||||
1. Azure Static Web App 리소스 생성
|
||||
2. GitHub 저장소 연결
|
||||
3. 빌드 설정 구성:
|
||||
- 앱 위치: `quiz-app`
|
||||
- 출력 위치: `dist`
|
||||
4. GitHub Actions 워크플로우가 푸시 시 자동 배포
|
||||
|
||||
### 문서 사이트
|
||||
```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
|
||||
- 저장소에 개발 컨테이너 구성 포함
|
||||
- Codespaces가 Python 및 Node.js 환경 자동 설정
|
||||
- GitHub UI를 통해 저장소를 Codespace에서 열기
|
||||
- 모든 종속성이 자동으로 설치됨
|
||||
|
||||
## Pull Request 지침
|
||||
|
||||
### 제출 전
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR 제목 형식
|
||||
- 명확하고 설명적인 제목 사용
|
||||
- 형식: `[컴포넌트] 간단한 설명`
|
||||
- 예시:
|
||||
- `[Lesson 7] Fix Python notebook import error`
|
||||
- `[Quiz App] Add German translation`
|
||||
- `[Docs] Update README with new prerequisites`
|
||||
|
||||
### 필수 검사
|
||||
- 모든 코드가 오류 없이 실행되는지 확인
|
||||
- 노트북이 완전히 실행되는지 검증
|
||||
- Vue.js 애플리케이션이 성공적으로 빌드되는지 확인
|
||||
- 문서 링크가 작동하는지 확인
|
||||
- 수정된 경우 퀴즈 애플리케이션 테스트
|
||||
- 번역이 일관된 구조를 유지하는지 확인
|
||||
|
||||
### 기여 지침
|
||||
- 기존 코드 스타일 및 패턴 준수
|
||||
- 복잡한 로직에 대한 설명 주석 추가
|
||||
- 관련 문서 업데이트
|
||||
- 변경 사항이 적용되는 경우 여러 강의 모듈에서 테스트
|
||||
- CONTRIBUTING.md 파일 검토
|
||||
|
||||
## 추가 참고 사항
|
||||
|
||||
### 사용된 주요 라이브러리
|
||||
- **pandas**: 데이터 조작 및 분석
|
||||
- **numpy**: 수치 계산
|
||||
- **matplotlib**: 데이터 시각화 및 플로팅
|
||||
- **seaborn**: 통계적 데이터 시각화 (일부 강의)
|
||||
- **scikit-learn**: 머신 러닝 (고급 강의)
|
||||
|
||||
### 데이터 파일 작업
|
||||
- 데이터 파일은 `data/` 폴더 또는 강의별 디렉토리에 위치
|
||||
- 대부분의 노트북은 상대 경로에서 데이터 파일을 기대
|
||||
- CSV 파일이 주요 데이터 형식
|
||||
- 일부 강의는 비관계형 데이터 예제를 위해 JSON 사용
|
||||
|
||||
### 다국어 지원
|
||||
- GitHub Actions를 통한 40개 이상의 언어 번역
|
||||
- 번역 워크플로우는 `.github/workflows/co-op-translator.yml`에 있음
|
||||
- 번역은 언어 코드가 포함된 `translations/` 폴더에 저장
|
||||
- 퀴즈 번역은 `quiz-app/src/assets/translations/`에 저장
|
||||
|
||||
### 개발 환경 옵션
|
||||
1. **로컬 개발**: Python, Jupyter, Node.js를 로컬에 설치
|
||||
2. **GitHub Codespaces**: 클라우드 기반 즉시 개발 환경
|
||||
3. **VS Code Dev Containers**: 로컬 컨테이너 기반 개발
|
||||
4. **Binder**: 클라우드에서 노트북 실행 (구성된 경우)
|
||||
|
||||
### 강의 내용 지침
|
||||
- 각 강의는 독립적이지만 이전 개념을 기반으로 구축
|
||||
- 강의 전 퀴즈는 사전 지식을 테스트
|
||||
- 강의 후 퀴즈는 학습을 강화
|
||||
- 과제는 실습 연습 제공
|
||||
- 스케치노트는 시각적 요약 제공
|
||||
|
||||
### 일반적인 문제 해결
|
||||
|
||||
**Jupyter 커널 문제:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm 설치 실패:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**노트북에서 Import 오류:**
|
||||
- 필요한 모든 라이브러리가 설치되었는지 확인
|
||||
- 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 검토
|
||||
- 월간 콘텐츠 리뷰 및 업데이트
|
||||
|
||||
---
|
||||
|
||||
**면책 조항**:
|
||||
이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있습니다. 원본 문서의 원어 버전이 권위 있는 출처로 간주되어야 합니다. 중요한 정보의 경우, 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:46:40+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "lt"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Projekto apžvalga
|
||||
|
||||
„Data Science for Beginners“ yra išsamus 10 savaičių, 20 pamokų mokymo planas, sukurtas „Microsoft Azure Cloud Advocates“. Šis saugykla yra mokymosi šaltinis, kuris moko pagrindinių duomenų mokslo koncepcijų per projektines pamokas, įskaitant Jupyter užrašų knygeles, interaktyvius testus ir praktines užduotis.
|
||||
|
||||
**Pagrindinės technologijos:**
|
||||
- **Jupyter užrašų knygelės**: Pagrindinė mokymosi priemonė naudojant Python 3
|
||||
- **Python bibliotekos**: pandas, numpy, matplotlib duomenų analizei ir vizualizacijai
|
||||
- **Vue.js 2**: Testų programa (quiz-app aplankas)
|
||||
- **Docsify**: Dokumentacijos svetainės generatorius neprisijungus
|
||||
- **Node.js/npm**: Paketų valdymas JavaScript komponentams
|
||||
- **Markdown**: Visas pamokų turinys ir dokumentacija
|
||||
|
||||
**Architektūra:**
|
||||
- Daugiakalbė mokomoji saugykla su plačiomis vertimais
|
||||
- Struktūrizuota į pamokų modulius (nuo 1-Introduction iki 6-Data-Science-In-Wild)
|
||||
- Kiekviena pamoka apima README, užrašų knygeles, užduotis ir testus
|
||||
- Savarankiška Vue.js testų programa prieš/pamokos vertinimui
|
||||
- GitHub Codespaces ir VS Code dev konteinerių palaikymas
|
||||
|
||||
## Nustatymo komandos
|
||||
|
||||
### Saugyklos nustatymas
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python aplinkos nustatymas
|
||||
```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
|
||||
```
|
||||
|
||||
### Testų programos nustatymas
|
||||
```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 dokumentacijos serveris
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Vizualizacijos projektų nustatymas
|
||||
Vizualizacijos projektams, pvz., meaningful-visualizations (13 pamoka):
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Vystymo darbo eiga
|
||||
|
||||
### Darbas su Jupyter užrašų knygelėmis
|
||||
1. Paleiskite Jupyter saugyklos šaknyje: `jupyter notebook`
|
||||
2. Naršykite į norimą pamokos aplanką
|
||||
3. Atidarykite `.ipynb` failus, kad atliktumėte pratimus
|
||||
4. Užrašų knygelės yra savarankiškos su paaiškinimais ir kodų langeliais
|
||||
5. Dauguma užrašų knygelių naudoja pandas, numpy ir matplotlib - įsitikinkite, kad jos įdiegtos
|
||||
|
||||
### Pamokos struktūra
|
||||
Kiekviena pamoka paprastai apima:
|
||||
- `README.md` - Pagrindinis pamokos turinys su teorija ir pavyzdžiais
|
||||
- `notebook.ipynb` - Praktiniai Jupyter užrašų knygelės pratimai
|
||||
- `assignment.ipynb` arba `assignment.md` - Praktinės užduotys
|
||||
- `solution/` aplankas - Sprendimų užrašų knygelės ir kodas
|
||||
- `images/` aplankas - Palaikomos vizualinės medžiagos
|
||||
|
||||
### Testų programos kūrimas
|
||||
- Vue.js 2 programa su karštu perkrovimu vystymo metu
|
||||
- Testai saugomi `quiz-app/src/assets/translations/`
|
||||
- Kiekviena kalba turi savo vertimų aplanką (en, fr, es ir kt.)
|
||||
- Testų numeracija prasideda nuo 0 ir tęsiasi iki 39 (iš viso 40 testų)
|
||||
|
||||
### Vertimų pridėjimas
|
||||
- Vertimai dedami į `translations/` aplanką saugyklos šaknyje
|
||||
- Kiekviena kalba turi pilną pamokų struktūrą, atspindinčią anglų kalbą
|
||||
- Automatinis vertimas per GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Testavimo instrukcijos
|
||||
|
||||
### Testų programos testavimas
|
||||
```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
|
||||
```
|
||||
|
||||
### Užrašų knygelių testavimas
|
||||
- Automatinės testavimo sistemos užrašų knygelėms nėra
|
||||
- Rankinis patikrinimas: Paleiskite visus langelius iš eilės, kad įsitikintumėte, jog nėra klaidų
|
||||
- Patikrinkite, ar duomenų failai yra pasiekiami ir ar rezultatai generuojami teisingai
|
||||
- Įsitikinkite, kad vizualizacijos tinkamai rodomos
|
||||
|
||||
### Dokumentacijos testavimas
|
||||
```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
|
||||
```
|
||||
|
||||
### Kodo kokybės patikrinimai
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Kodo stiliaus gairės
|
||||
|
||||
### Python (Jupyter užrašų knygelės)
|
||||
- Laikykitės PEP 8 stiliaus gairių Python kodui
|
||||
- Naudokite aiškius kintamųjų pavadinimus, kurie paaiškina analizuojamus duomenis
|
||||
- Prieš kodų langelius įtraukite markdown langelius su paaiškinimais
|
||||
- Kodų langelius laikykite sutelktus į vieną koncepciją ar operaciją
|
||||
- Naudokite pandas duomenų manipuliacijai, matplotlib vizualizacijai
|
||||
- Įprastas importavimo modelis:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Laikykitės Vue.js 2 stiliaus gairių ir geriausių praktikų
|
||||
- ESLint konfigūracija `quiz-app/package.json`
|
||||
- Naudokite Vue vieno failo komponentus (.vue failai)
|
||||
- Išlaikykite komponentų pagrįstą architektūrą
|
||||
- Prieš įsipareigojimus paleiskite `npm run lint`
|
||||
|
||||
### Markdown dokumentacija
|
||||
- Naudokite aiškią antraščių hierarchiją (# ## ### ir kt.)
|
||||
- Įtraukite kodų blokus su kalbos specifikatoriais
|
||||
- Pridėkite alternatyvų tekstą vaizdams
|
||||
- Nuorodos į susijusias pamokas ir išteklius
|
||||
- Išlaikykite tinkamą eilučių ilgį, kad būtų lengviau skaityti
|
||||
|
||||
### Failų organizavimas
|
||||
- Pamokų turinys numeruotuose aplankuose (01-defining-data-science ir kt.)
|
||||
- Sprendimai dedami į atskirus `solution/` aplankus
|
||||
- Vertimai atspindi anglų struktūrą `translations/` aplanke
|
||||
- Duomenų failai laikomi `data/` arba pamokai skirtuose aplankuose
|
||||
|
||||
## Kūrimas ir diegimas
|
||||
|
||||
### Testų programos diegimas
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps diegimas
|
||||
Testų programa gali būti diegiama į Azure Static Web Apps:
|
||||
1. Sukurkite Azure Static Web App resursą
|
||||
2. Prisijunkite prie GitHub saugyklos
|
||||
3. Konfigūruokite kūrimo nustatymus:
|
||||
- Programos vieta: `quiz-app`
|
||||
- Išvesties vieta: `dist`
|
||||
4. GitHub Actions darbo eiga automatiškai diegs po pakeitimų
|
||||
|
||||
### Dokumentacijos svetainė
|
||||
```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
|
||||
- Saugykla apima dev konteinerio konfigūraciją
|
||||
- Codespaces automatiškai nustato Python ir Node.js aplinką
|
||||
- Atidarykite saugyklą Codespace per GitHub UI
|
||||
- Visos priklausomybės įdiegiamos automatiškai
|
||||
|
||||
## Pull Request gairės
|
||||
|
||||
### Prieš pateikimą
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR pavadinimo formatas
|
||||
- Naudokite aiškius, aprašomuosius pavadinimus
|
||||
- Formatavimas: `[Komponentas] Trumpas aprašymas`
|
||||
- Pavyzdžiai:
|
||||
- `[Pamoka 7] Ištaisykite Python užrašų knygelės importavimo klaidą`
|
||||
- `[Testų programa] Pridėkite vokiečių kalbos vertimą`
|
||||
- `[Dokumentai] Atnaujinkite README su naujais reikalavimais`
|
||||
|
||||
### Reikalingi patikrinimai
|
||||
- Įsitikinkite, kad visas kodas veikia be klaidų
|
||||
- Patikrinkite, ar užrašų knygelės vykdomos visiškai
|
||||
- Patvirtinkite, kad Vue.js programos sėkmingai kuriamos
|
||||
- Patikrinkite, ar dokumentacijos nuorodos veikia
|
||||
- Testuokite testų programą, jei ji buvo pakeista
|
||||
- Patikrinkite, ar vertimai išlaiko nuoseklią struktūrą
|
||||
|
||||
### Prisidėjimo gairės
|
||||
- Laikykitės esamo kodo stiliaus ir modelių
|
||||
- Pridėkite paaiškinamuosius komentarus sudėtingai logikai
|
||||
- Atnaujinkite susijusią dokumentaciją
|
||||
- Testuokite pakeitimus skirtinguose pamokų moduliuose, jei taikoma
|
||||
- Peržiūrėkite CONTRIBUTING.md failą
|
||||
|
||||
## Papildomos pastabos
|
||||
|
||||
### Naudojamos bibliotekos
|
||||
- **pandas**: Duomenų manipuliacija ir analizė
|
||||
- **numpy**: Skaitmeninis skaičiavimas
|
||||
- **matplotlib**: Duomenų vizualizacija ir grafikai
|
||||
- **seaborn**: Statistinė duomenų vizualizacija (kai kurios pamokos)
|
||||
- **scikit-learn**: Mašininis mokymasis (pažangios pamokos)
|
||||
|
||||
### Darbas su duomenų failais
|
||||
- Duomenų failai yra `data/` aplanke arba pamokai skirtuose kataloguose
|
||||
- Dauguma užrašų knygelių tikisi duomenų failų santykiniais keliais
|
||||
- CSV failai yra pagrindinis duomenų formatas
|
||||
- Kai kurios pamokos naudoja JSON nestruktūrizuotų duomenų pavyzdžiams
|
||||
|
||||
### Daugiakalbė parama
|
||||
- 40+ kalbų vertimai per automatizuotus GitHub Actions
|
||||
- Vertimo darbo eiga `.github/workflows/co-op-translator.yml`
|
||||
- Vertimai `translations/` aplanke su kalbos kodais
|
||||
- Testų vertimai `quiz-app/src/assets/translations/`
|
||||
|
||||
### Vystymo aplinkos pasirinkimai
|
||||
1. **Vietinis vystymas**: Įdiekite Python, Jupyter, Node.js vietoje
|
||||
2. **GitHub Codespaces**: Debesų pagrindu veikianti momentinė vystymo aplinka
|
||||
3. **VS Code Dev Containers**: Vietinė konteinerių pagrindu veikianti aplinka
|
||||
4. **Binder**: Paleiskite užrašų knygeles debesyje (jei sukonfigūruota)
|
||||
|
||||
### Pamokų turinio gairės
|
||||
- Kiekviena pamoka yra savarankiška, bet remiasi ankstesnėmis koncepcijomis
|
||||
- Prieš pamoką testai tikrina ankstesnes žinias
|
||||
- Po pamokos testai stiprina mokymąsi
|
||||
- Užduotys suteikia praktinę patirtį
|
||||
- Sketchnotes pateikia vizualines santraukas
|
||||
|
||||
### Dažniausiai pasitaikančių problemų sprendimas
|
||||
|
||||
**Jupyter branduolio problemos:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm diegimo klaidos:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Importavimo klaidos užrašų knygelėse:**
|
||||
- Patikrinkite, ar visos reikalingos bibliotekos yra įdiegtos
|
||||
- Patikrinkite Python versijos suderinamumą (rekomenduojama Python 3.7+)
|
||||
- Įsitikinkite, kad virtuali aplinka yra aktyvuota
|
||||
|
||||
**Docsify neveikia:**
|
||||
- Patikrinkite, ar serveris paleistas iš saugyklos šaknies
|
||||
- Patikrinkite, ar egzistuoja `index.html`
|
||||
- Įsitikinkite tinkamu tinklo prieinamumu (3000 prievadas)
|
||||
|
||||
### Našumo apsvarstymai
|
||||
- Dideli duomenų rinkiniai gali užtrukti, kol bus įkelti užrašų knygelėse
|
||||
- Vizualizacijos generavimas gali būti lėtas sudėtingiems grafams
|
||||
- Vue.js vystymo serveris leidžia greitą iteraciją su karštu perkrovimu
|
||||
- Produkcijos kūrimai yra optimizuoti ir minimizuoti
|
||||
|
||||
### Saugumo pastabos
|
||||
- Jokių jautrių duomenų ar kredencialų neturėtų būti įsipareigojama
|
||||
- Naudokite aplinkos kintamuosius bet kokiems API raktams debesų pamokose
|
||||
- Pamokos, susijusios su Azure, gali reikalauti Azure paskyros kredencialų
|
||||
- Laikykite priklausomybes atnaujintas dėl saugumo pataisų
|
||||
|
||||
## Prisidėjimas prie vertimų
|
||||
- Automatiniai vertimai valdomi per GitHub Actions
|
||||
- Rankiniai pataisymai laukiami dėl vertimo tikslumo
|
||||
- Laikykitės esamos vertimų aplankų struktūros
|
||||
- Atnaujinkite testų nuorodas, kad įtrauktumėte kalbos parametrą: `?loc=fr`
|
||||
- Testuokite išverstus pamokas, kad įsitikintumėte tinkamu rodymu
|
||||
|
||||
## Susiję ištekliai
|
||||
- Pagrindinis mokymo planas: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Studentų centras: https://docs.microsoft.com/learn/student-hub
|
||||
- Diskusijų forumas: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Kiti Microsoft mokymo planai: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Projekto priežiūra
|
||||
- Reguliarūs atnaujinimai, kad turinys būtų aktualus
|
||||
- Bendruomenės indėlis laukiami
|
||||
- Problemos stebimos GitHub
|
||||
- PR peržiūrimi mokymo plano prižiūrėtojų
|
||||
- Mėnesiniai turinio peržiūros ir atnaujinimai
|
||||
|
||||
---
|
||||
|
||||
**Atsakomybės apribojimas**:
|
||||
Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba turėtų būti laikomas autoritetingu šaltiniu. Kritinei informacijai rekomenduojama naudoti profesionalų žmogaus vertimą. Mes neprisiimame atsakomybės už nesusipratimus ar neteisingą interpretaciją, atsiradusią dėl šio vertimo naudojimo.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:13:42+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "mr"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## प्रकल्पाचा आढावा
|
||||
|
||||
डेटा सायन्स फॉर बिगिनर्स हा मायक्रोसॉफ्ट Azure क्लाउड अॅडव्होकेट्सद्वारे तयार केलेला 10 आठवड्यांचा, 20 धड्यांचा व्यापक अभ्यासक्रम आहे. हे रिपॉझिटरी प्रकल्प-आधारित धड्यांद्वारे मूलभूत डेटा सायन्स संकल्पना शिकवणारे शिक्षण संसाधन आहे, ज्यामध्ये Jupyter नोटबुक्स, परस्पर क्विझ आणि प्रॅक्टिकल असाइनमेंट्स समाविष्ट आहेत.
|
||||
|
||||
**मुख्य तंत्रज्ञान:**
|
||||
- **Jupyter नोटबुक्स**: 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 dev कंटेनर समर्थन
|
||||
|
||||
## सेटअप कमांड्स
|
||||
|
||||
### रिपॉझिटरी सेटअप
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python वातावरण सेटअप
|
||||
```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
|
||||
```
|
||||
|
||||
### क्विझ अॅप्लिकेशन सेटअप
|
||||
```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 दस्तऐवज सर्व्हर
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### व्हिज्युअलायझेशन प्रकल्प सेटअप
|
||||
अर्थपूर्ण व्हिज्युअलायझेशनसारख्या प्रकल्पांसाठी (धडा 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
|
||||
```
|
||||
|
||||
|
||||
## विकास कार्यप्रवाह
|
||||
|
||||
### Jupyter नोटबुक्ससह काम करणे
|
||||
1. रिपॉझिटरी रूटमध्ये Jupyter सुरू करा: `jupyter notebook`
|
||||
2. इच्छित धड्याच्या फोल्डरमध्ये जा
|
||||
3. `.ipynb` फाइल्स उघडा आणि सराव करा
|
||||
4. नोटबुक्स स्पष्टीकरण आणि कोड सेल्ससह स्वयंपूर्ण आहेत
|
||||
5. बहुतेक नोटबुक्स 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)
|
||||
|
||||
## चाचणी सूचना
|
||||
|
||||
### क्विझ अॅप्लिकेशन चाचणी
|
||||
```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
|
||||
```
|
||||
|
||||
### नोटबुक चाचणी
|
||||
- नोटबुक्ससाठी कोणतेही स्वयंचलित चाचणी फ्रेमवर्क अस्तित्वात नाही
|
||||
- मॅन्युअल सत्यापन: सर्व सेल्स क्रमाने चालवा आणि त्रुटी नसल्याची खात्री करा
|
||||
- डेटा फाइल्स प्रवेशयोग्य आहेत आणि आउटपुट योग्यरित्या तयार होतात याची खात्री करा
|
||||
- व्हिज्युअलायझेशन योग्यरित्या रेंडर होतात याची तपासणी करा
|
||||
|
||||
### दस्तऐवज चाचणी
|
||||
```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
|
||||
```
|
||||
|
||||
### कोड गुणवत्ता तपासणी
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## कोड शैली मार्गदर्शक तत्त्वे
|
||||
|
||||
### Python (Jupyter नोटबुक्स)
|
||||
- Python कोडसाठी PEP 8 शैली मार्गदर्शकांचे अनुसरण करा
|
||||
- विश्लेषित डेटा स्पष्ट करणारी व्हेरिएबल नावे वापरा
|
||||
- कोड सेल्सच्या आधी स्पष्टीकरणांसह Markdown सेल्स समाविष्ट करा
|
||||
- कोड सेल्स एका संकल्पनेवर किंवा ऑपरेशनवर केंद्रित ठेवा
|
||||
- डेटा मॅनिप्युलेशनसाठी pandas, व्हिज्युअलायझेशनसाठी matplotlib वापरा
|
||||
- सामान्य आयात पॅटर्न:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Vue.js 2 शैली मार्गदर्शक आणि सर्वोत्तम पद्धतींचे अनुसरण करा
|
||||
- `quiz-app/package.json` मध्ये ESLint कॉन्फिगरेशन
|
||||
- Vue सिंगल-फाइल घटक (.vue फाइल्स) वापरा
|
||||
- घटक-आधारित आर्किटेक्चर राखा
|
||||
- बदल करण्यापूर्वी `npm run lint` चालवा
|
||||
|
||||
### Markdown दस्तऐवज
|
||||
- स्पष्ट शीर्षकांची श्रेणी (# ## ### इ.) वापरा
|
||||
- भाषा निर्दिष्ट करणाऱ्या कोड ब्लॉक्स समाविष्ट करा
|
||||
- प्रतिमांसाठी alt टेक्स्ट जोडा
|
||||
- संबंधित धडे आणि संसाधनांशी लिंक करा
|
||||
- वाचनीयतेसाठी ओळींची लांबी योग्य ठेवा
|
||||
|
||||
### फाइल्सचे आयोजन
|
||||
- क्रमांकित फोल्डर्समध्ये धड्यांची सामग्री (01-defining-data-science, इ.)
|
||||
- `solution/` उपफोल्डर्समध्ये सोल्यूशन्स
|
||||
- `translations/` फोल्डरमध्ये इंग्रजी संरचनेचे प्रतिबिंब
|
||||
- डेटा फाइल्स `data/` किंवा धड्यांसाठी विशिष्ट फोल्डर्समध्ये ठेवा
|
||||
|
||||
## बिल्ड आणि डिप्लॉयमेंट
|
||||
|
||||
### क्विझ अॅप्लिकेशन डिप्लॉयमेंट
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps डिप्लॉयमेंट
|
||||
क्विझ-अॅप Azure Static Web Apps वर डिप्लॉय केले जाऊ शकते:
|
||||
1. Azure Static Web App संसाधन तयार करा
|
||||
2. GitHub रिपॉझिटरीशी कनेक्ट करा
|
||||
3. बिल्ड सेटिंग्ज कॉन्फिगर करा:
|
||||
- अॅप स्थान: `quiz-app`
|
||||
- आउटपुट स्थान: `dist`
|
||||
4. GitHub Actions वर्कफ्लो पुश केल्यावर स्वयंचलितपणे डिप्लॉय होईल
|
||||
|
||||
### दस्तऐवज साइट
|
||||
```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
|
||||
- रिपॉझिटरीमध्ये dev कंटेनर कॉन्फिगरेशन समाविष्ट आहे
|
||||
- Codespaces स्वयंचलितपणे Python आणि Node.js वातावरण सेट करते
|
||||
- GitHub UI द्वारे रिपॉझिटरी Codespace मध्ये उघडा
|
||||
- सर्व आवश्यक गोष्टी स्वयंचलितपणे स्थापित होतात
|
||||
|
||||
## पुल रिक्वेस्ट मार्गदर्शक तत्त्वे
|
||||
|
||||
### सबमिट करण्यापूर्वी
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR शीर्षक स्वरूप
|
||||
- स्पष्ट, वर्णनात्मक शीर्षके वापरा
|
||||
- स्वरूप: `[घटक] संक्षिप्त वर्णन`
|
||||
- उदाहरणे:
|
||||
- `[Lesson 7] Python नोटबुक आयात त्रुटी दुरुस्त करा`
|
||||
- `[Quiz App] जर्मन अनुवाद जोडा`
|
||||
- `[Docs] नवीन पूर्वापेक्षांसह README अपडेट करा`
|
||||
|
||||
### आवश्यक तपासण्या
|
||||
- सर्व कोड त्रुटीशिवाय चालतो याची खात्री करा
|
||||
- नोटबुक्स पूर्णपणे चालवतात याची पुष्टी करा
|
||||
- Vue.js अॅप्स यशस्वीरित्या बिल्ड होतात याची खात्री करा
|
||||
- दस्तऐवज दुवे कार्यरत आहेत याची तपासणी करा
|
||||
- क्विझ अॅप्लिकेशन बदलल्यास चाचणी करा
|
||||
- अनुवाद संरचना सुसंगत ठेवतात याची पुष्टी करा
|
||||
|
||||
### योगदान मार्गदर्शक तत्त्वे
|
||||
- विद्यमान कोड शैली आणि नमुन्यांचे अनुसरण करा
|
||||
- जटिल लॉजिकसाठी स्पष्टीकरणात्मक टिप्पण्या जोडा
|
||||
- संबंधित दस्तऐवज अपडेट करा
|
||||
- बदल लागू असल्यास विविध धड्यांमध्ये चाचणी करा
|
||||
- CONTRIBUTING.md फाइल पुनरावलोकन करा
|
||||
|
||||
## अतिरिक्त टिप्पण्या
|
||||
|
||||
### सामान्यतः वापरल्या जाणाऱ्या लायब्ररी
|
||||
- **pandas**: डेटा मॅनिप्युलेशन आणि विश्लेषण
|
||||
- **numpy**: संख्यात्मक संगणन
|
||||
- **matplotlib**: डेटा व्हिज्युअलायझेशन आणि प्लॉटिंग
|
||||
- **seaborn**: सांख्यिकीय डेटा व्हिज्युअलायझेशन (काही धडे)
|
||||
- **scikit-learn**: मशीन लर्निंग (प्रगत धडे)
|
||||
|
||||
### डेटा फाइल्ससह काम करणे
|
||||
- डेटा फाइल्स `data/` फोल्डर किंवा धड्यासाठी विशिष्ट निर्देशिकांमध्ये स्थित आहेत
|
||||
- बहुतेक नोटबुक्स डेटा फाइल्स सापेक्ष पथांमध्ये अपेक्षित करतात
|
||||
- CSV फाइल्स प्राथमिक डेटा स्वरूप आहेत
|
||||
- काही धडे नॉन-रिलेशनल डेटा उदाहरणांसाठी JSON वापरतात
|
||||
|
||||
### बहुभाषिक समर्थन
|
||||
- स्वयंचलित GitHub Actions द्वारे 40+ भाषांमध्ये अनुवाद
|
||||
- `.github/workflows/co-op-translator.yml` मध्ये अनुवाद कार्यप्रवाह
|
||||
- `translations/` फोल्डरमध्ये भाषा कोडसह अनुवाद
|
||||
- क्विझ अनुवाद `quiz-app/src/assets/translations/` मध्ये
|
||||
|
||||
### विकास वातावरण पर्याय
|
||||
1. **स्थानिक विकास**: स्थानिकरित्या Python, Jupyter, Node.js स्थापित करा
|
||||
2. **GitHub Codespaces**: क्लाउड-आधारित त्वरित विकास वातावरण
|
||||
3. **VS Code Dev Containers**: स्थानिक कंटेनर-आधारित विकास
|
||||
4. **Binder**: क्लाउडमध्ये नोटबुक्स लॉन्च करा (कॉन्फिगर केल्यास)
|
||||
|
||||
### धड्यांची सामग्री मार्गदर्शक तत्त्वे
|
||||
- प्रत्येक धडा स्वतंत्र आहे परंतु मागील संकल्पनांवर आधारित आहे
|
||||
- प्री-धडा क्विझेस पूर्व ज्ञानाची चाचणी करतात
|
||||
- पोस्ट-धडा क्विझेस शिकवलेले बळकट करतात
|
||||
- असाइनमेंट्स प्रॅक्टिकल सराव प्रदान करतात
|
||||
- स्केच नोट्स व्हिज्युअल सारांश प्रदान करतात
|
||||
|
||||
### सामान्य समस्या सोडवणे
|
||||
|
||||
**Jupyter कर्नल समस्या:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm इंस्टॉल अपयश:**
|
||||
```bash
|
||||
# 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 dev सर्व्हर जलद पुनरावृत्तीसाठी हॉट-रिलोड सक्षम करते
|
||||
- उत्पादन बिल्ड्स ऑप्टिमाइझ आणि मिनिफाईड आहेत
|
||||
|
||||
### सुरक्षा टिप्पण्या
|
||||
- संवेदनशील डेटा किंवा क्रेडेन्शियल्स कमिट करू नका
|
||||
- क्लाउड धड्यांमध्ये कोणत्याही 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 पुनरावलोकन
|
||||
- मासिक सामग्री पुनरावलोकन आणि अद्यतने
|
||||
|
||||
---
|
||||
|
||||
**अस्वीकरण**:
|
||||
हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून भाषांतरित करण्यात आला आहे. आम्ही अचूकतेसाठी प्रयत्नशील असलो तरी, कृपया लक्षात ठेवा की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेचा अभाव असू शकतो. मूळ भाषेतील दस्तऐवज हा अधिकृत स्रोत मानला जावा. महत्त्वाच्या माहितीसाठी, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराचा वापर करून उद्भवलेल्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थासाठी आम्ही जबाबदार राहणार नाही.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:31:51+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "ms"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Gambaran Projek
|
||||
|
||||
Data Science for Beginners adalah kurikulum komprehensif selama 10 minggu dengan 20 pelajaran yang dicipta oleh Microsoft Azure Cloud Advocates. Repositori ini adalah sumber pembelajaran yang mengajar konsep asas sains data melalui pelajaran berasaskan projek, termasuk Jupyter notebooks, kuiz interaktif, dan tugasan praktikal.
|
||||
|
||||
**Teknologi Utama:**
|
||||
- **Jupyter Notebooks**: Medium pembelajaran utama menggunakan Python 3
|
||||
- **Perpustakaan Python**: pandas, numpy, matplotlib untuk analisis dan visualisasi data
|
||||
- **Vue.js 2**: Aplikasi kuiz (folder quiz-app)
|
||||
- **Docsify**: Penjana laman dokumentasi untuk akses luar talian
|
||||
- **Node.js/npm**: Pengurusan pakej untuk komponen JavaScript
|
||||
- **Markdown**: Semua kandungan pelajaran dan dokumentasi
|
||||
|
||||
**Arkitektur:**
|
||||
- Repositori pendidikan pelbagai bahasa dengan terjemahan yang meluas
|
||||
- Disusun dalam modul pelajaran (1-Pengenalan hingga 6-Data-Science-In-Wild)
|
||||
- Setiap pelajaran termasuk README, notebooks, tugasan, dan kuiz
|
||||
- Aplikasi kuiz Vue.js yang berdiri sendiri untuk penilaian sebelum/selepas pelajaran
|
||||
- Sokongan GitHub Codespaces dan kontena dev VS Code
|
||||
|
||||
## Perintah Persediaan
|
||||
|
||||
### Persediaan Repositori
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Persediaan Persekitaran Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Persediaan Aplikasi Kuiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Pelayan Dokumentasi Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Persediaan Projek Visualisasi
|
||||
Untuk projek visualisasi seperti meaningful-visualizations (pelajaran 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
|
||||
```
|
||||
|
||||
|
||||
## Aliran Kerja Pembangunan
|
||||
|
||||
### Bekerja dengan Jupyter Notebooks
|
||||
1. Mulakan Jupyter di akar repositori: `jupyter notebook`
|
||||
2. Navigasi ke folder pelajaran yang diingini
|
||||
3. Buka fail `.ipynb` untuk menjalankan latihan
|
||||
4. Notebooks adalah berdiri sendiri dengan penjelasan dan sel kod
|
||||
5. Kebanyakan notebooks menggunakan pandas, numpy, dan matplotlib - pastikan ini dipasang
|
||||
|
||||
### Struktur Pelajaran
|
||||
Setiap pelajaran biasanya mengandungi:
|
||||
- `README.md` - Kandungan utama pelajaran dengan teori dan contoh
|
||||
- `notebook.ipynb` - Latihan praktikal Jupyter notebook
|
||||
- `assignment.ipynb` atau `assignment.md` - Tugasan praktikal
|
||||
- Folder `solution/` - Notebook dan kod penyelesaian
|
||||
- Folder `images/` - Bahan visual sokongan
|
||||
|
||||
### Pembangunan Aplikasi Kuiz
|
||||
- Aplikasi Vue.js 2 dengan hot-reload semasa pembangunan
|
||||
- Kuiz disimpan dalam `quiz-app/src/assets/translations/`
|
||||
- Setiap bahasa mempunyai folder terjemahan sendiri (en, fr, es, dll.)
|
||||
- Penomboran kuiz bermula dari 0 hingga 39 (40 kuiz keseluruhan)
|
||||
|
||||
### Menambah Terjemahan
|
||||
- Terjemahan diletakkan dalam folder `translations/` di akar repositori
|
||||
- Setiap bahasa mempunyai struktur pelajaran lengkap yang mencerminkan bahasa Inggeris
|
||||
- Terjemahan automatik melalui GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Arahan Pengujian
|
||||
|
||||
### Pengujian Aplikasi Kuiz
|
||||
```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
|
||||
```
|
||||
|
||||
### Pengujian Notebook
|
||||
- Tiada rangka kerja ujian automatik untuk notebooks
|
||||
- Pengesahan manual: Jalankan semua sel secara berurutan untuk memastikan tiada ralat
|
||||
- Pastikan fail data boleh diakses dan output dihasilkan dengan betul
|
||||
- Periksa bahawa visualisasi dipaparkan dengan baik
|
||||
|
||||
### Pengujian Dokumentasi
|
||||
```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
|
||||
```
|
||||
|
||||
### Pemeriksaan Kualiti Kod
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Garis Panduan Gaya Kod
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Ikuti garis panduan gaya PEP 8 untuk kod Python
|
||||
- Gunakan nama pemboleh ubah yang jelas yang menerangkan data yang dianalisis
|
||||
- Sertakan sel markdown dengan penjelasan sebelum sel kod
|
||||
- Kekalkan sel kod fokus pada konsep atau operasi tunggal
|
||||
- Gunakan pandas untuk manipulasi data, matplotlib untuk visualisasi
|
||||
- Corak import biasa:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Ikuti panduan gaya Vue.js 2 dan amalan terbaik
|
||||
- Konfigurasi ESLint dalam `quiz-app/package.json`
|
||||
- Gunakan komponen tunggal Vue (.vue files)
|
||||
- Kekalkan seni bina berasaskan komponen
|
||||
- Jalankan `npm run lint` sebelum membuat perubahan
|
||||
|
||||
### Dokumentasi Markdown
|
||||
- Gunakan hierarki tajuk yang jelas (# ## ### dll.)
|
||||
- Sertakan blok kod dengan penentu bahasa
|
||||
- Tambahkan teks alt untuk imej
|
||||
- Pautkan ke pelajaran dan sumber berkaitan
|
||||
- Kekalkan panjang baris yang munasabah untuk kebolehbacaan
|
||||
|
||||
### Organisasi Fail
|
||||
- Kandungan pelajaran dalam folder bernombor (01-defining-data-science, dll.)
|
||||
- Penyelesaian dalam subfolder `solution/` khusus
|
||||
- Terjemahan mencerminkan struktur bahasa Inggeris dalam folder `translations/`
|
||||
- Simpan fail data dalam folder `data/` atau folder khusus pelajaran
|
||||
|
||||
## Pembinaan dan Penerapan
|
||||
|
||||
### Penerapan Aplikasi Kuiz
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Penerapan Azure Static Web Apps
|
||||
Aplikasi kuiz boleh diterapkan ke Azure Static Web Apps:
|
||||
1. Buat sumber Azure Static Web App
|
||||
2. Sambungkan ke repositori GitHub
|
||||
3. Konfigurasi tetapan pembinaan:
|
||||
- Lokasi aplikasi: `quiz-app`
|
||||
- Lokasi output: `dist`
|
||||
4. Aliran kerja GitHub Actions akan menerapkan secara automatik pada push
|
||||
|
||||
### Laman Dokumentasi
|
||||
```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
|
||||
- Repositori termasuk konfigurasi kontena dev
|
||||
- Codespaces secara automatik menyediakan persekitaran Python dan Node.js
|
||||
- Buka repositori dalam Codespace melalui UI GitHub
|
||||
- Semua kebergantungan dipasang secara automatik
|
||||
|
||||
## Garis Panduan Permintaan Tarik
|
||||
|
||||
### Sebelum Menghantar
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format Tajuk PR
|
||||
- Gunakan tajuk yang jelas dan deskriptif
|
||||
- Format: `[Komponen] Penerangan ringkas`
|
||||
- Contoh:
|
||||
- `[Pelajaran 7] Betulkan ralat import notebook Python`
|
||||
- `[Aplikasi Kuiz] Tambah terjemahan bahasa Jerman`
|
||||
- `[Dokumen] Kemas kini README dengan prasyarat baru`
|
||||
|
||||
### Pemeriksaan Diperlukan
|
||||
- Pastikan semua kod berjalan tanpa ralat
|
||||
- Sahkan notebook dijalankan sepenuhnya
|
||||
- Pastikan aplikasi Vue.js dibina dengan berjaya
|
||||
- Periksa bahawa pautan dokumentasi berfungsi
|
||||
- Uji aplikasi kuiz jika diubah
|
||||
- Sahkan terjemahan mengekalkan struktur yang konsisten
|
||||
|
||||
### Garis Panduan Sumbangan
|
||||
- Ikuti gaya dan corak kod yang sedia ada
|
||||
- Tambahkan komen penjelasan untuk logik yang kompleks
|
||||
- Kemas kini dokumentasi yang relevan
|
||||
- Uji perubahan merentasi modul pelajaran yang berbeza jika berkenaan
|
||||
- Semak fail CONTRIBUTING.md
|
||||
|
||||
## Nota Tambahan
|
||||
|
||||
### Perpustakaan Biasa Digunakan
|
||||
- **pandas**: Manipulasi dan analisis data
|
||||
- **numpy**: Pengkomputeran numerik
|
||||
- **matplotlib**: Visualisasi dan plot data
|
||||
- **seaborn**: Visualisasi data statistik (beberapa pelajaran)
|
||||
- **scikit-learn**: Pembelajaran mesin (pelajaran lanjutan)
|
||||
|
||||
### Bekerja dengan Fail Data
|
||||
- Fail data terletak dalam folder `data/` atau direktori khusus pelajaran
|
||||
- Kebanyakan notebooks mengharapkan fail data dalam laluan relatif
|
||||
- Fail CSV adalah format data utama
|
||||
- Beberapa pelajaran menggunakan JSON untuk contoh data bukan relasional
|
||||
|
||||
### Sokongan Pelbagai Bahasa
|
||||
- 40+ terjemahan bahasa melalui GitHub Actions automatik
|
||||
- Aliran kerja terjemahan dalam `.github/workflows/co-op-translator.yml`
|
||||
- Terjemahan dalam folder `translations/` dengan kod bahasa
|
||||
- Terjemahan kuiz dalam `quiz-app/src/assets/translations/`
|
||||
|
||||
### Pilihan Persekitaran Pembangunan
|
||||
1. **Pembangunan Tempatan**: Pasang Python, Jupyter, Node.js secara tempatan
|
||||
2. **GitHub Codespaces**: Persekitaran pembangunan segera berasaskan awan
|
||||
3. **Kontena Dev VS Code**: Pembangunan berasaskan kontena tempatan
|
||||
4. **Binder**: Lancarkan notebooks dalam awan (jika dikonfigurasi)
|
||||
|
||||
### Garis Panduan Kandungan Pelajaran
|
||||
- Setiap pelajaran berdiri sendiri tetapi membina konsep sebelumnya
|
||||
- Kuiz sebelum pelajaran menguji pengetahuan terdahulu
|
||||
- Kuiz selepas pelajaran mengukuhkan pembelajaran
|
||||
- Tugasan menyediakan latihan praktikal
|
||||
- Sketchnotes menyediakan ringkasan visual
|
||||
|
||||
### Menyelesaikan Masalah Biasa
|
||||
|
||||
**Isu Kernel Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Kegagalan Pemasangan npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Ralat Import dalam Notebooks:**
|
||||
- Pastikan semua perpustakaan yang diperlukan dipasang
|
||||
- Periksa keserasian versi Python (Python 3.7+ disyorkan)
|
||||
- Pastikan persekitaran maya diaktifkan
|
||||
|
||||
**Docsify Tidak Memuatkan:**
|
||||
- Pastikan anda melayani dari akar repositori
|
||||
- Periksa bahawa `index.html` wujud
|
||||
- Pastikan akses rangkaian yang betul (port 3000)
|
||||
|
||||
### Pertimbangan Prestasi
|
||||
- Dataset besar mungkin mengambil masa untuk dimuatkan dalam notebooks
|
||||
- Rendering visualisasi boleh menjadi perlahan untuk plot yang kompleks
|
||||
- Pelayan dev Vue.js membolehkan hot-reload untuk iterasi cepat
|
||||
- Pembinaan pengeluaran dioptimumkan dan diminimumkan
|
||||
|
||||
### Nota Keselamatan
|
||||
- Tiada data sensitif atau kelayakan harus dikomit
|
||||
- Gunakan pembolehubah persekitaran untuk sebarang kunci API dalam pelajaran awan
|
||||
- Pelajaran berkaitan Azure mungkin memerlukan kelayakan akaun Azure
|
||||
- Kekalkan kebergantungan terkini untuk tampalan keselamatan
|
||||
|
||||
## Menyumbang kepada Terjemahan
|
||||
- Terjemahan automatik diuruskan melalui GitHub Actions
|
||||
- Pembetulan manual dialu-alukan untuk ketepatan terjemahan
|
||||
- Ikuti struktur folder terjemahan yang sedia ada
|
||||
- Kemas kini pautan kuiz untuk memasukkan parameter bahasa: `?loc=fr`
|
||||
- Uji pelajaran yang diterjemahkan untuk paparan yang betul
|
||||
|
||||
## Sumber Berkaitan
|
||||
- Kurikulum utama: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum Perbincangan: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Kurikulum Microsoft lain: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Penyelenggaraan Projek
|
||||
- Kemas kini berkala untuk memastikan kandungan terkini
|
||||
- Sumbangan komuniti dialu-alukan
|
||||
- Isu dijejaki di GitHub
|
||||
- PR disemak oleh penyelenggara kurikulum
|
||||
- Semakan dan kemas kini kandungan bulanan
|
||||
|
||||
---
|
||||
|
||||
**Penafian**:
|
||||
Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk memastikan ketepatan, sila ambil perhatian bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang berwibawa. Untuk maklumat yang kritikal, terjemahan manusia profesional adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:44:36+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "my"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## ပရောဂျက်အကျဉ်းချုပ်
|
||||
|
||||
Data Science for Beginners သည် Microsoft Azure Cloud Advocates မှဖန်တီးထားသော ၁၀ ပတ်၊ ၂၀ သင်ခန်းစာများပါဝင်သော အကျယ်အဝန်းရှိသင်ရိုးတစ်ခုဖြစ်သည်။ ဤ repository သည် Jupyter notebooks, interactive quizzes, နှင့် လက်တွေ့လုပ်ငန်းများပါဝင်သော project-based သင်ခန်းစာများမှတဆင့် အခြေခံ data science အယူအဆများကို သင်ကြားပေးသော သင်ယူရေးအရင်းအမြစ်တစ်ခုဖြစ်သည်။
|
||||
|
||||
**အဓိကနည်းပညာများ:**
|
||||
- **Jupyter Notebooks**: Python 3 ကိုအသုံးပြုသော အဓိကသင်ယူရေးအကောင်အထည်
|
||||
- **Python Libraries**: pandas, numpy, matplotlib ကို data analysis နှင့် visualization အတွက်အသုံးပြု
|
||||
- **Vue.js 2**: Quiz application (quiz-app folder)
|
||||
- **Docsify**: Offline access အတွက် documentation site generator
|
||||
- **Node.js/npm**: JavaScript components အတွက် package management
|
||||
- **Markdown**: သင်ခန်းစာအကြောင်းအရာနှင့် documentation အားလုံး
|
||||
|
||||
**Architecture:**
|
||||
- ဘာသာစကားများစွာပါဝင်သော သင်ကြားရေး repository
|
||||
- သင်ခန်းစာ module များ (1-Introduction မှ 6-Data-Science-In-Wild အထိ) အဖြစ်ဖွဲ့စည်းထား
|
||||
- သင်ခန်းစာတစ်ခုစီတွင် README, notebooks, assignments, နှင့် quizzes ပါဝင်သည်
|
||||
- သင်ခန်းစာမတိုင်မီ/ပြီးနောက် စမ်းသပ်မှုများအတွက် standalone Vue.js quiz application
|
||||
- GitHub Codespaces နှင့် VS Code dev containers အထောက်အပံ့
|
||||
|
||||
## Setup Commands
|
||||
|
||||
### Repository Setup
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python Environment Setup
|
||||
```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
|
||||
```
|
||||
|
||||
### Quiz Application Setup
|
||||
```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 Documentation Server
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Visualization Projects Setup
|
||||
meaningful-visualizations (lesson 13) ကဲ့သို့သော visualization projects အတွက်:
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Jupyter Notebooks နှင့်အလုပ်လုပ်ခြင်း
|
||||
1. Repository root တွင် Jupyter ကိုစတင်ပါ: `jupyter notebook`
|
||||
2. လိုအပ်သော သင်ခန်းစာ folder သို့သွားပါ
|
||||
3. `.ipynb` ဖိုင်များကိုဖွင့်ပြီး လေ့ကျင့်မှုများကိုလုပ်ဆောင်ပါ
|
||||
4. Notebooks တွင် ရှင်းလင်းချက်များနှင့် code cells ပါဝင်ပြီး အပြည့်အစုံဖြစ်သည်
|
||||
5. notebooks များအများစုသည် pandas, numpy, နှင့် matplotlib ကိုအသုံးပြုသည် - ဤ library များကို install လုပ်ထားရန်သေချာပါ
|
||||
|
||||
### သင်ခန်းစာဖွဲ့စည်းမှု
|
||||
သင်ခန်းစာတစ်ခုစီတွင် အများအားဖြင့်:
|
||||
- `README.md` - သင်ခန်းစာအကြောင်းအရာအဓိကနှင့် သီအိုရီ၊ ဥပမာများ
|
||||
- `notebook.ipynb` - လက်တွေ့ Jupyter notebook လေ့ကျင့်မှုများ
|
||||
- `assignment.ipynb` သို့မဟုတ် `assignment.md` - လေ့ကျင့်မှုအလုပ်များ
|
||||
- `solution/` folder - ဖြေရှင်းချက် notebooks နှင့် code
|
||||
- `images/` folder - အထောက်အကူပြု visual materials
|
||||
|
||||
### Quiz Application Development
|
||||
- Vue.js 2 application သည် hot-reload ဖြင့် development အတွင်းအလုပ်လုပ်သည်
|
||||
- Quizzes များကို `quiz-app/src/assets/translations/` တွင်သိမ်းဆည်းထားသည်
|
||||
- ဘာသာစကားတစ်ခုစီတွင် translation folder (en, fr, es, စသည်) ရှိသည်
|
||||
- Quiz အရေအတွက်သည် 0 မှစတင်ပြီး 39 အထိရှိသည် (စုစုပေါင်း 40 quizzes)
|
||||
|
||||
### Translations ထည့်သွင်းခြင်း
|
||||
- Translations များကို repository root တွင် `translations/` folder တွင်ထား
|
||||
- ဘာသာစကားတစ်ခုစီသည် အင်္ဂလိပ်ဘာသာစကားမှ mirrored lesson structure ရှိသည်
|
||||
- GitHub Actions (co-op-translator.yml) မှတဆင့် automated translation
|
||||
|
||||
## Testing Instructions
|
||||
|
||||
### Quiz Application Testing
|
||||
```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
|
||||
```
|
||||
|
||||
### Notebook Testing
|
||||
- notebooks အတွက် automated test framework မရှိပါ
|
||||
- Manual validation: Cell အားလုံးကို အစဉ်လိုက် run လုပ်ပြီး error မရှိကြောင်းသေချာပါ
|
||||
- Data files များရရှိနိုင်မှုနှင့် output များ generate ဖြစ်ကြောင်းစစ်ဆေးပါ
|
||||
- Visualizations များမှန်ကန်စွာ render ဖြစ်ကြောင်းစစ်ဆေးပါ
|
||||
|
||||
### Documentation Testing
|
||||
```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
|
||||
```
|
||||
|
||||
### Code Quality Checks
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Python code အတွက် PEP 8 style guidelines ကိုလိုက်နာပါ
|
||||
- အချက်အလက်ကိုရှင်းလင်းစွာဖော်ပြသော variable names ကိုအသုံးပြုပါ
|
||||
- Markdown cells တွင် code cells မတိုင်မီ ရှင်းလင်းချက်များထည့်ပါ
|
||||
- Code cells များကို concept တစ်ခုစီ သို့မဟုတ် operation တစ်ခုစီအတွက် အာရုံစိုက်ပါ
|
||||
- Data manipulation အတွက် pandas, visualization အတွက် matplotlib ကိုအသုံးပြုပါ
|
||||
- Import pattern အများအားဖြင့်:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Vue.js 2 style guide နှင့် best practices ကိုလိုက်နာပါ
|
||||
- `quiz-app/package.json` တွင် ESLint configuration ရှိသည်
|
||||
- Vue single-file components (.vue files) ကိုအသုံးပြုပါ
|
||||
- Component-based architecture ကိုထိန်းသိမ်းပါ
|
||||
- Commit မလုပ်မီ `npm run lint` ကို run လုပ်ပါ
|
||||
|
||||
### Markdown Documentation
|
||||
- ရှင်းလင်းသော headings hierarchy (# ## ### စသည်) ကိုအသုံးပြုပါ
|
||||
- Language specifiers ပါသော code blocks ထည့်ပါ
|
||||
- Images အတွက် alt text ထည့်ပါ
|
||||
- သက်ဆိုင်သော သင်ခန်းစာများနှင့် အရင်းအမြစ်များ link လုပ်ပါ
|
||||
- ဖတ်ရှုရလွယ်ကူစေရန် line lengths ကိုသင့်တင့်စွာထားပါ
|
||||
|
||||
### File Organization
|
||||
- သင်ခန်းစာအကြောင်းအရာကို အမှတ်ပေးထားသော folders (01-defining-data-science စသည်) တွင်ထား
|
||||
- Solutions များကို `solution/` subfolders တွင်ထား
|
||||
- Translations များကို `translations/` folder တွင် အင်္ဂလိပ် structure ကို mirror လုပ်ထား
|
||||
- Data files များကို `data/` သို့မဟုတ် သင်ခန်းစာ-specific folders တွင်ထား
|
||||
|
||||
## Build and Deployment
|
||||
|
||||
### Quiz Application Deployment
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps Deployment
|
||||
Quiz-app ကို Azure Static Web Apps တွင် deploy လုပ်နိုင်သည်:
|
||||
1. Azure Static Web App resource တစ်ခုဖန်တီးပါ
|
||||
2. GitHub repository ကိုချိတ်ဆက်ပါ
|
||||
3. Build settings ကို configure လုပ်ပါ:
|
||||
- App location: `quiz-app`
|
||||
- Output location: `dist`
|
||||
4. GitHub Actions workflow သည် push လုပ်သောအခါ auto-deploy လုပ်မည်
|
||||
|
||||
### Documentation Site
|
||||
```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
|
||||
- Repository တွင် dev container configuration ပါဝင်သည်
|
||||
- Codespaces သည် Python နှင့် Node.js environment ကို auto-setup လုပ်သည်
|
||||
- GitHub UI မှတဆင့် repository ကို Codespace တွင်ဖွင့်ပါ
|
||||
- Dependencies အားလုံးကို auto-install လုပ်သည်
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Submit မလုပ်မီ
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR Title Format
|
||||
- ရှင်းလင်းသော၊ ဖော်ပြချက်ပေးသော title များကိုအသုံးပြုပါ
|
||||
- Format: `[Component] Brief description`
|
||||
- ဥပမာများ:
|
||||
- `[Lesson 7] Fix Python notebook import error`
|
||||
- `[Quiz App] Add German translation`
|
||||
- `[Docs] Update README with new prerequisites`
|
||||
|
||||
### Required Checks
|
||||
- Code အားလုံး error မရှိကြောင်းသေချာပါ
|
||||
- Notebooks အားလုံးကို အပြည့်အစုံ run လုပ်ပါ
|
||||
- Vue.js apps များကို build လုပ်ပြီးအောင်မြင်ကြောင်းစစ်ဆေးပါ
|
||||
- Documentation links အားလုံးအလုပ်လုပ်ကြောင်းစစ်ဆေးပါ
|
||||
- Quiz application ကိုပြောင်းလဲထားပါက စမ်းသပ်ပါ
|
||||
- Translations များ structure တူညီမှုရှိကြောင်းအတည်ပြုပါ
|
||||
|
||||
### Contribution Guidelines
|
||||
- ရှိပြီးသား code style နှင့် patterns ကိုလိုက်နာပါ
|
||||
- ရှုပ်ထွေးသော logic အတွက် ရှင်းလင်းချက် comment များထည့်ပါ
|
||||
- သက်ဆိုင်သော documentation ကို update လုပ်ပါ
|
||||
- သင်ခန်းစာ module များအနှံ့ စမ်းသပ်ပါ (သက်ဆိုင်ပါက)
|
||||
- CONTRIBUTING.md ဖိုင်ကိုကြည့်ပါ
|
||||
|
||||
## အပိုအချက်အလက်များ
|
||||
|
||||
### Common Libraries Used
|
||||
- **pandas**: Data manipulation နှင့် analysis
|
||||
- **numpy**: Numerical computing
|
||||
- **matplotlib**: Data visualization နှင့် plotting
|
||||
- **seaborn**: Statistical data visualization (သင်ခန်းစာအချို့)
|
||||
- **scikit-learn**: Machine learning (အဆင့်မြင့်သင်ခန်းစာများ)
|
||||
|
||||
### Data Files နှင့်အလုပ်လုပ်ခြင်း
|
||||
- Data files များကို `data/` folder သို့မဟုတ် သင်ခန်းစာ-specific directories တွင်ထား
|
||||
- Notebooks များအများစုသည် relative paths တွင် data files များကိုမျှော်လင့်သည်
|
||||
- CSV files သည် primary data format ဖြစ်သည်
|
||||
- Non-relational data ဥပမာများအတွက် JSON ကိုသုံးသော သင်ခန်းစာအချို့ရှိသည်
|
||||
|
||||
### Multilingual Support
|
||||
- Automated GitHub Actions မှတဆင့် 40+ ဘာသာစကား translation များ
|
||||
- Translation workflow ကို `.github/workflows/co-op-translator.yml` တွင်ထား
|
||||
- Translations များကို `translations/` folder တွင် language codes ဖြင့်ထား
|
||||
- Quiz translations များကို `quiz-app/src/assets/translations/` တွင်ထား
|
||||
|
||||
### Development Environment Options
|
||||
1. **Local Development**: Python, Jupyter, Node.js ကို locally install လုပ်ပါ
|
||||
2. **GitHub Codespaces**: Cloud-based instant development environment
|
||||
3. **VS Code Dev Containers**: Local container-based development
|
||||
4. **Binder**: Cloud တွင် notebooks များကို launch လုပ်ပါ (configure လုပ်ထားပါက)
|
||||
|
||||
### Lesson Content Guidelines
|
||||
- သင်ခန်းစာတစ်ခုစီသည် standalone ဖြစ်ပြီး အရင် concept များကိုအခြေခံထားသည်
|
||||
- Pre-lesson quizzes သည် အရင်အတန်းအကြောင်းအရာကိုစမ်းသပ်သည်
|
||||
- Post-lesson quizzes သည် သင်ယူမှုကို reinforcement လုပ်သည်
|
||||
- Assignments များသည် လက်တွေ့လေ့ကျင့်မှုများပေးသည်
|
||||
- Sketchnotes များသည် visual summaries ပေးသည်
|
||||
|
||||
### Troubleshooting Common Issues
|
||||
|
||||
**Jupyter Kernel Issues:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm Install Failures:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Import Errors in Notebooks:**
|
||||
- လိုအပ်သော library များအားလုံး install လုပ်ထားကြောင်းစစ်ဆေးပါ
|
||||
- Python version compatibility ကိုစစ်ဆေးပါ (Python 3.7+ recommend)
|
||||
- Virtual environment ကို activate လုပ်ထားကြောင်းသေချာပါ
|
||||
|
||||
**Docsify Not Loading:**
|
||||
- Repository root မှ serve လုပ်နေကြောင်းစစ်ဆေးပါ
|
||||
- `index.html` ရှိကြောင်းစစ်ဆေးပါ
|
||||
- သင့် network access (port 3000) မှန်ကန်ကြောင်းစစ်ဆေးပါ
|
||||
|
||||
### Performance Considerations
|
||||
- အကြီးမားသော datasets များသည် notebooks တွင် load လုပ်ရန်အချိန်ယူနိုင်သည်
|
||||
- Visualization rendering သည် ရှုပ်ထွေးသော plots များအတွက်နှေးနိုင်သည်
|
||||
- Vue.js dev server သည် hot-reload ကို enable လုပ်သည်
|
||||
- Production builds များသည် optimized နှင့် minified ဖြစ်သည်
|
||||
|
||||
### Security Notes
|
||||
- Sensitive data သို့မဟုတ် credentials များကို commit မလုပ်ပါနှင့်
|
||||
- Cloud lessons များတွင် API keys အတွက် environment variables ကိုအသုံးပြုပါ
|
||||
- Azure သက်ဆိုင်သော သင်ခန်းစာများတွင် Azure account credentials လိုအပ်နိုင်သည်
|
||||
- Security patches အတွက် dependencies များကို update လုပ်ထားပါ
|
||||
|
||||
## Contributing to Translations
|
||||
- Automated translations များကို GitHub Actions မှစီမံခန့်ခွဲထားသည်
|
||||
- Translation accuracy အတွက် manual corrections များကိုကြိုဆိုပါသည်
|
||||
- ရှိပြီးသား translation folder structure ကိုလိုက်နာပါ
|
||||
- Quiz links များကို language parameter ပါအောင် update လုပ်ပါ: `?loc=fr`
|
||||
- Translated lessons များကို rendering မှန်ကန်ကြောင်းစမ်းသပ်ပါ
|
||||
|
||||
## Related Resources
|
||||
- Main curriculum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Discussion Forum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Other Microsoft curricula: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Project Maintenance
|
||||
- အကြောင်းအရာကို current ဖြစ်အောင် regular updates လုပ်ပါ
|
||||
- Community contributions များကိုကြိုဆိုပါသည်
|
||||
- GitHub တွင် issues များကို tracking လုပ်ပါ
|
||||
- PRs များကို curriculum maintainers မှ review လုပ်ပါ
|
||||
- Content များကို လစဉ် review နှင့် update လုပ်ပါ
|
||||
|
||||
---
|
||||
|
||||
**အကြောင်းကြားချက်**:
|
||||
ဤစာရွက်စာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) ကို အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှုအတွက် ကြိုးစားနေသော်လည်း၊ အလိုအလျောက် ဘာသာပြန်ခြင်းတွင် အမှားများ သို့မဟုတ် မတိကျမှုများ ပါဝင်နိုင်သည်ကို သတိပြုပါ။ မူရင်းဘာသာစကားဖြင့် ရေးသားထားသော စာရွက်စာတမ်းကို အာဏာတရားရှိသော ရင်းမြစ်အဖြစ် သတ်မှတ်သင့်ပါသည်။ အရေးကြီးသော အချက်အလက်များအတွက် လူက ဘာသာပြန်ခြင်းကို အကြံပြုပါသည်။ ဤဘာသာပြန်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော အလွဲအလွဲအချော်များ သို့မဟုတ် အနားယူမှုမှားများအတွက် ကျွန်ုပ်တို့သည် တာဝန်မယူပါ။
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:28:02+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "nl"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Projectoverzicht
|
||||
|
||||
Data Science for Beginners is een uitgebreide 10-weekse, 20-lessen curriculum ontwikkeld door Microsoft Azure Cloud Advocates. De repository is een leerbron die fundamentele data science-concepten onderwijst via projectgebaseerde lessen, inclusief Jupyter-notebooks, interactieve quizzen en praktische opdrachten.
|
||||
|
||||
**Belangrijke technologieën:**
|
||||
- **Jupyter Notebooks**: Primair leermedium met Python 3
|
||||
- **Python-bibliotheken**: pandas, numpy, matplotlib voor data-analyse en visualisatie
|
||||
- **Vue.js 2**: Quizapplicatie (quiz-app map)
|
||||
- **Docsify**: Documentatiesitegenerator voor offline toegang
|
||||
- **Node.js/npm**: Pakketbeheer voor JavaScript-componenten
|
||||
- **Markdown**: Alle lesinhoud en documentatie
|
||||
|
||||
**Architectuur:**
|
||||
- Meertalige educatieve repository met uitgebreide vertalingen
|
||||
- Gestructureerd in lesmodules (1-Introduction tot 6-Data-Science-In-Wild)
|
||||
- Elke les bevat README, notebooks, opdrachten en quizzen
|
||||
- Zelfstandige Vue.js quizapplicatie voor pre/post-les beoordelingen
|
||||
- Ondersteuning voor GitHub Codespaces en VS Code dev containers
|
||||
|
||||
## Setupcommando's
|
||||
|
||||
### Repository Setup
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python-omgeving instellen
|
||||
```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
|
||||
```
|
||||
|
||||
### Quizapplicatie instellen
|
||||
```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 documentatieserver
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Visualisatieprojecten instellen
|
||||
Voor visualisatieprojecten zoals meaningful-visualizations (les 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
|
||||
```
|
||||
|
||||
|
||||
## Ontwikkelworkflow
|
||||
|
||||
### Werken met Jupyter Notebooks
|
||||
1. Start Jupyter in de root van de repository: `jupyter notebook`
|
||||
2. Navigeer naar de gewenste lesmap
|
||||
3. Open `.ipynb` bestanden om oefeningen door te nemen
|
||||
4. Notebooks zijn zelfstandig met uitleg en codecellen
|
||||
5. De meeste notebooks gebruiken pandas, numpy en matplotlib - zorg ervoor dat deze geïnstalleerd zijn
|
||||
|
||||
### Lesstructuur
|
||||
Elke les bevat doorgaans:
|
||||
- `README.md` - Hoofdlesinhoud met theorie en voorbeelden
|
||||
- `notebook.ipynb` - Praktische Jupyter-notebook oefeningen
|
||||
- `assignment.ipynb` of `assignment.md` - Oefenopdrachten
|
||||
- `solution/` map - Oplossingsnotebooks en code
|
||||
- `images/` map - Ondersteunend visueel materiaal
|
||||
|
||||
### Ontwikkeling van de quizapplicatie
|
||||
- Vue.js 2 applicatie met hot-reload tijdens ontwikkeling
|
||||
- Quizzen opgeslagen in `quiz-app/src/assets/translations/`
|
||||
- Elke taal heeft zijn eigen vertaalmap (en, fr, es, etc.)
|
||||
- Quiznummering begint bij 0 en loopt op tot 39 (40 quizzen totaal)
|
||||
|
||||
### Vertalingen toevoegen
|
||||
- Vertalingen gaan in de `translations/` map in de root van de repository
|
||||
- Elke taal heeft een complete lesstructuur die de Engelse structuur weerspiegelt
|
||||
- Geautomatiseerde vertaling via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Testinstructies
|
||||
|
||||
### Testen van de quizapplicatie
|
||||
```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
|
||||
```
|
||||
|
||||
### Testen van notebooks
|
||||
- Er bestaat geen geautomatiseerd testframework voor notebooks
|
||||
- Handmatige validatie: Voer alle cellen achter elkaar uit om te controleren op fouten
|
||||
- Controleer of databestanden toegankelijk zijn en outputs correct worden gegenereerd
|
||||
- Controleer of visualisaties correct worden weergegeven
|
||||
|
||||
### Testen van documentatie
|
||||
```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
|
||||
```
|
||||
|
||||
### Controle van codekwaliteit
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Richtlijnen voor codestijl
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Volg PEP 8 stijlrichtlijnen voor Python-code
|
||||
- Gebruik duidelijke variabelenamen die de geanalyseerde data beschrijven
|
||||
- Voeg markdown-cellen toe met uitleg vóór codecellen
|
||||
- Houd codecellen gericht op één concept of operatie
|
||||
- Gebruik pandas voor datamanipulatie, matplotlib voor visualisatie
|
||||
- Veelgebruikte importpatroon:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Volg Vue.js 2 stijlrichtlijnen en best practices
|
||||
- ESLint-configuratie in `quiz-app/package.json`
|
||||
- Gebruik Vue single-file componenten (.vue bestanden)
|
||||
- Behoud componentgebaseerde architectuur
|
||||
- Voer `npm run lint` uit voordat je wijzigingen commit
|
||||
|
||||
### Markdown-documentatie
|
||||
- Gebruik een duidelijke koppenhiërarchie (# ## ### etc.)
|
||||
- Voeg codeblokken toe met taalspecificaties
|
||||
- Voeg alt-tekst toe voor afbeeldingen
|
||||
- Link naar gerelateerde lessen en bronnen
|
||||
- Houd regellengtes redelijk voor leesbaarheid
|
||||
|
||||
### Bestandsorganisatie
|
||||
- Lesinhoud in genummerde mappen (01-defining-data-science, etc.)
|
||||
- Oplossingen in toegewijde `solution/` submappen
|
||||
- Vertalingen spiegelen de Engelse structuur in de `translations/` map
|
||||
- Houd databestanden in `data/` of les-specifieke mappen
|
||||
|
||||
## Build en deployment
|
||||
|
||||
### Deployment van de quizapplicatie
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps Deployment
|
||||
De quiz-app kan worden gedeployed naar Azure Static Web Apps:
|
||||
1. Maak een Azure Static Web App resource aan
|
||||
2. Verbind met de GitHub-repository
|
||||
3. Configureer buildinstellingen:
|
||||
- App-locatie: `quiz-app`
|
||||
- Output-locatie: `dist`
|
||||
4. GitHub Actions workflow zal automatisch deployen bij een push
|
||||
|
||||
### Documentatiesite
|
||||
```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
|
||||
- Repository bevat dev container configuratie
|
||||
- Codespaces stelt automatisch Python- en Node.js-omgeving in
|
||||
- Open repository in Codespace via GitHub UI
|
||||
- Alle afhankelijkheden worden automatisch geïnstalleerd
|
||||
|
||||
## Richtlijnen voor pull requests
|
||||
|
||||
### Voor het indienen
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR-titel formaat
|
||||
- Gebruik duidelijke, beschrijvende titels
|
||||
- Formaat: `[Component] Korte beschrijving`
|
||||
- Voorbeelden:
|
||||
- `[Les 7] Fix Python notebook importfout`
|
||||
- `[Quiz App] Voeg Duitse vertaling toe`
|
||||
- `[Docs] Update README met nieuwe vereisten`
|
||||
|
||||
### Vereiste controles
|
||||
- Zorg ervoor dat alle code zonder fouten draait
|
||||
- Controleer dat notebooks volledig worden uitgevoerd
|
||||
- Bevestig dat Vue.js apps succesvol bouwen
|
||||
- Controleer dat documentatielinks werken
|
||||
- Test de quizapplicatie indien gewijzigd
|
||||
- Controleer of vertalingen een consistente structuur behouden
|
||||
|
||||
### Richtlijnen voor bijdragen
|
||||
- Volg bestaande codestijl en patronen
|
||||
- Voeg verklarende opmerkingen toe voor complexe logica
|
||||
- Update relevante documentatie
|
||||
- Test wijzigingen in verschillende lesmodules indien van toepassing
|
||||
- Bekijk het CONTRIBUTING.md bestand
|
||||
|
||||
## Aanvullende opmerkingen
|
||||
|
||||
### Veelgebruikte bibliotheken
|
||||
- **pandas**: Datamanipulatie en analyse
|
||||
- **numpy**: Numerieke berekeningen
|
||||
- **matplotlib**: Datavisualisatie en grafieken
|
||||
- **seaborn**: Statistische datavisualisatie (sommige lessen)
|
||||
- **scikit-learn**: Machine learning (gevorderde lessen)
|
||||
|
||||
### Werken met databestanden
|
||||
- Databestanden bevinden zich in de `data/` map of les-specifieke mappen
|
||||
- De meeste notebooks verwachten databestanden in relatieve paden
|
||||
- CSV-bestanden zijn het primaire dataformaat
|
||||
- Sommige lessen gebruiken JSON voor voorbeelden van niet-relationele data
|
||||
|
||||
### Meertalige ondersteuning
|
||||
- 40+ taalvertalingen via geautomatiseerde GitHub Actions
|
||||
- Vertaalworkflow in `.github/workflows/co-op-translator.yml`
|
||||
- Vertalingen in de `translations/` map met taalcodes
|
||||
- Quizvertalingen in `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opties voor ontwikkelomgeving
|
||||
1. **Lokale ontwikkeling**: Installeer Python, Jupyter, Node.js lokaal
|
||||
2. **GitHub Codespaces**: Cloudgebaseerde directe ontwikkelomgeving
|
||||
3. **VS Code Dev Containers**: Lokale containergebaseerde ontwikkeling
|
||||
4. **Binder**: Start notebooks in de cloud (indien geconfigureerd)
|
||||
|
||||
### Richtlijnen voor lesinhoud
|
||||
- Elke les is zelfstandig maar bouwt voort op eerdere concepten
|
||||
- Pre-les quizzen testen voorkennis
|
||||
- Post-les quizzen versterken het geleerde
|
||||
- Opdrachten bieden praktische oefening
|
||||
- Sketchnotes bieden visuele samenvattingen
|
||||
|
||||
### Veelvoorkomende problemen oplossen
|
||||
|
||||
**Jupyter Kernel Problemen:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm Installatiefouten:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Importfouten in notebooks:**
|
||||
- Controleer of alle vereiste bibliotheken zijn geïnstalleerd
|
||||
- Controleer Python-versiecompatibiliteit (Python 3.7+ aanbevolen)
|
||||
- Zorg ervoor dat de virtuele omgeving is geactiveerd
|
||||
|
||||
**Docsify Laadt Niet:**
|
||||
- Controleer of je serveert vanuit de root van de repository
|
||||
- Controleer of `index.html` bestaat
|
||||
- Zorg voor juiste netwerktoegang (poort 3000)
|
||||
|
||||
### Prestatieoverwegingen
|
||||
- Grote datasets kunnen tijd kosten om te laden in notebooks
|
||||
- Rendering van visualisaties kan traag zijn voor complexe grafieken
|
||||
- Vue.js dev server biedt hot-reload voor snelle iteratie
|
||||
- Productiebouws zijn geoptimaliseerd en geminimaliseerd
|
||||
|
||||
### Veiligheidsopmerkingen
|
||||
- Geen gevoelige data of inloggegevens mogen worden gecommit
|
||||
- Gebruik omgevingsvariabelen voor API-sleutels in cloudlessen
|
||||
- Azure-gerelateerde lessen kunnen Azure-accountgegevens vereisen
|
||||
- Houd afhankelijkheden up-to-date voor beveiligingspatches
|
||||
|
||||
## Bijdragen aan vertalingen
|
||||
- Geautomatiseerde vertalingen beheerd via GitHub Actions
|
||||
- Handmatige correcties welkom voor vertaalnauwkeurigheid
|
||||
- Volg bestaande structuur van vertaalmappen
|
||||
- Update quizlinks om taalparameter toe te voegen: `?loc=fr`
|
||||
- Test vertaalde lessen op correcte weergave
|
||||
|
||||
## Gerelateerde bronnen
|
||||
- Hoofdcurriculum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Discussieforum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Andere Microsoft curricula: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Projectonderhoud
|
||||
- Regelmatige updates om inhoud actueel te houden
|
||||
- Bijdragen van de gemeenschap welkom
|
||||
- Problemen worden bijgehouden op GitHub
|
||||
- PR's worden beoordeeld door curriculumbeheerders
|
||||
- Maandelijkse inhoudsbeoordelingen en updates
|
||||
|
||||
---
|
||||
|
||||
**Disclaimer**:
|
||||
Dit document is vertaald met behulp van de AI-vertalingsservice [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u zich ervan bewust te zijn dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor cruciale informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:26:12+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "no"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Prosjektoversikt
|
||||
|
||||
Data Science for Beginners er et omfattende 10-ukers, 20-leksjons pensum opprettet av Microsoft Azure Cloud Advocates. Repositoriet er en læringsressurs som lærer grunnleggende konsepter innen data science gjennom prosjektbaserte leksjoner, inkludert Jupyter-notebooks, interaktive quizer og praktiske oppgaver.
|
||||
|
||||
**Nøkkelteknologier:**
|
||||
- **Jupyter Notebooks**: Primært læringsmedium med Python 3
|
||||
- **Python-biblioteker**: pandas, numpy, matplotlib for dataanalyse og visualisering
|
||||
- **Vue.js 2**: Quiz-applikasjon (quiz-app-mappe)
|
||||
- **Docsify**: Dokumentasjonsgenerator for offline tilgang
|
||||
- **Node.js/npm**: Pakkehåndtering for JavaScript-komponenter
|
||||
- **Markdown**: Alt leksjonsinnhold og dokumentasjon
|
||||
|
||||
**Arkitektur:**
|
||||
- Flerspråklig utdanningsrepository med omfattende oversettelser
|
||||
- Strukturert i leksjonsmoduler (1-Introduksjon til 6-Data-Science-In-Wild)
|
||||
- Hver leksjon inkluderer README, notebooks, oppgaver og quizer
|
||||
- Selvstendig Vue.js quiz-applikasjon for vurderinger før/etter leksjoner
|
||||
- Støtte for GitHub Codespaces og VS Code utviklingscontainere
|
||||
|
||||
## Oppsettskommandoer
|
||||
|
||||
### Repository-oppsett
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python-miljøoppsett
|
||||
```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
|
||||
```
|
||||
|
||||
### Oppsett av quiz-applikasjon
|
||||
```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 dokumentasjonsserver
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Oppsett av visualiseringsprosjekter
|
||||
For visualiseringsprosjekter som meaningful-visualizations (leksjon 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
|
||||
```
|
||||
|
||||
|
||||
## Utviklingsarbeidsflyt
|
||||
|
||||
### Arbeide med Jupyter Notebooks
|
||||
1. Start Jupyter i repository-roten: `jupyter notebook`
|
||||
2. Naviger til ønsket leksjonsmappe
|
||||
3. Åpne `.ipynb`-filer for å jobbe gjennom øvelser
|
||||
4. Notebooks er selvstendige med forklaringer og kodeceller
|
||||
5. De fleste notebooks bruker pandas, numpy og matplotlib - sørg for at disse er installert
|
||||
|
||||
### Leksjonsstruktur
|
||||
Hver leksjon inneholder typisk:
|
||||
- `README.md` - Hovedinnhold med teori og eksempler
|
||||
- `notebook.ipynb` - Praktiske Jupyter-notebook-øvelser
|
||||
- `assignment.ipynb` eller `assignment.md` - Praktiske oppgaver
|
||||
- `solution/`-mappe - Løsningsnotebooks og kode
|
||||
- `images/`-mappe - Støttende visuelle materialer
|
||||
|
||||
### Utvikling av quiz-applikasjon
|
||||
- Vue.js 2-applikasjon med hot-reload under utvikling
|
||||
- Quizer lagret i `quiz-app/src/assets/translations/`
|
||||
- Hvert språk har sin egen oversettelsesmappe (en, fr, es, etc.)
|
||||
- Quiznummerering starter på 0 og går opp til 39 (40 quizer totalt)
|
||||
|
||||
### Legge til oversettelser
|
||||
- Oversettelser legges i `translations/`-mappen i repository-roten
|
||||
- Hvert språk har komplett leksjonsstruktur speilet fra engelsk
|
||||
- Automatisk oversettelse via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Testinstruksjoner
|
||||
|
||||
### Testing av quiz-applikasjon
|
||||
```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
|
||||
```
|
||||
|
||||
### Testing av notebooks
|
||||
- Ingen automatisert testrammeverk finnes for notebooks
|
||||
- Manuell validering: Kjør alle celler i rekkefølge for å sikre ingen feil
|
||||
- Verifiser at datafiler er tilgjengelige og at utdata genereres korrekt
|
||||
- Sjekk at visualiseringer vises riktig
|
||||
|
||||
### Testing av dokumentasjon
|
||||
```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
|
||||
```
|
||||
|
||||
### Kvalitetssjekk av kode
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Retningslinjer for kodestil
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Følg PEP 8-stilretningslinjer for Python-kode
|
||||
- Bruk klare variabelnavn som forklarer dataene som analyseres
|
||||
- Inkluder markdown-celler med forklaringer før kodeceller
|
||||
- Hold kodeceller fokusert på enkeltkonsepter eller operasjoner
|
||||
- Bruk pandas for datamanipulering, matplotlib for visualisering
|
||||
- Vanlig importmønster:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Følg Vue.js 2-stilguide og beste praksis
|
||||
- ESLint-konfigurasjon i `quiz-app/package.json`
|
||||
- Bruk Vue single-file-komponenter (.vue-filer)
|
||||
- Oppretthold komponentbasert arkitektur
|
||||
- Kjør `npm run lint` før du sender inn endringer
|
||||
|
||||
### Markdown-dokumentasjon
|
||||
- Bruk klar overskriftsstruktur (# ## ### osv.)
|
||||
- Inkluder kodeblokker med språkspesifikasjoner
|
||||
- Legg til alt-tekst for bilder
|
||||
- Lenke til relaterte leksjoner og ressurser
|
||||
- Hold linjelengder rimelige for lesbarhet
|
||||
|
||||
### Filorganisering
|
||||
- Leksjonsinnhold i nummererte mapper (01-defining-data-science, etc.)
|
||||
- Løsninger i dedikerte `solution/`-undermapper
|
||||
- Oversettelser speiler engelsk struktur i `translations/`-mappen
|
||||
- Hold datafiler i `data/` eller leksjonsspesifikke mapper
|
||||
|
||||
## Bygging og distribusjon
|
||||
|
||||
### Distribusjon av quiz-applikasjon
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Distribusjon av Azure Static Web Apps
|
||||
Quiz-applikasjonen kan distribueres til Azure Static Web Apps:
|
||||
1. Opprett Azure Static Web App-ressurs
|
||||
2. Koble til GitHub-repository
|
||||
3. Konfigurer bygginnstillinger:
|
||||
- Applikasjonsplassering: `quiz-app`
|
||||
- Utdata-plassering: `dist`
|
||||
4. GitHub Actions-arbeidsflyt vil automatisk distribuere ved push
|
||||
|
||||
### Dokumentasjonsnettsted
|
||||
```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
|
||||
- Repository inkluderer utviklingscontainer-konfigurasjon
|
||||
- Codespaces setter automatisk opp Python- og Node.js-miljø
|
||||
- Åpne repository i Codespace via GitHub UI
|
||||
- Alle avhengigheter installeres automatisk
|
||||
|
||||
## Retningslinjer for pull requests
|
||||
|
||||
### Før innsending
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format for PR-titler
|
||||
- Bruk klare, beskrivende titler
|
||||
- Format: `[Komponent] Kort beskrivelse`
|
||||
- Eksempler:
|
||||
- `[Leksjon 7] Fiks Python-notebook importfeil`
|
||||
- `[Quiz App] Legg til tysk oversettelse`
|
||||
- `[Docs] Oppdater README med nye forutsetninger`
|
||||
|
||||
### Nødvendige sjekker
|
||||
- Sørg for at all kode kjører uten feil
|
||||
- Verifiser at notebooks kjører fullstendig
|
||||
- Bekreft at Vue.js-applikasjoner bygges vellykket
|
||||
- Sjekk at dokumentasjonslenker fungerer
|
||||
- Test quiz-applikasjonen hvis den er endret
|
||||
- Verifiser at oversettelser opprettholder konsistent struktur
|
||||
|
||||
### Retningslinjer for bidrag
|
||||
- Følg eksisterende kodestil og mønstre
|
||||
- Legg til forklarende kommentarer for kompleks logikk
|
||||
- Oppdater relevant dokumentasjon
|
||||
- Test endringer på tvers av ulike leksjonsmoduler hvis aktuelt
|
||||
- Se gjennom CONTRIBUTING.md-filen
|
||||
|
||||
## Tilleggsnotater
|
||||
|
||||
### Vanlige biblioteker brukt
|
||||
- **pandas**: Datamanipulering og analyse
|
||||
- **numpy**: Numerisk databehandling
|
||||
- **matplotlib**: Datavisualisering og plotting
|
||||
- **seaborn**: Statistisk datavisualisering (noen leksjoner)
|
||||
- **scikit-learn**: Maskinlæring (avanserte leksjoner)
|
||||
|
||||
### Arbeide med datafiler
|
||||
- Datafiler plassert i `data/`-mappen eller leksjonsspesifikke kataloger
|
||||
- De fleste notebooks forventer datafiler i relative stier
|
||||
- CSV-filer er primært dataformat
|
||||
- Noen leksjoner bruker JSON for eksempler på ikke-relasjonelle data
|
||||
|
||||
### Flerspråklig støtte
|
||||
- 40+ språkoversettelser via automatiserte GitHub Actions
|
||||
- Oversettelsesarbeidsflyt i `.github/workflows/co-op-translator.yml`
|
||||
- Oversettelser i `translations/`-mappen med språkkoder
|
||||
- Quiz-oversettelser i `quiz-app/src/assets/translations/`
|
||||
|
||||
### Utviklingsmiljøalternativer
|
||||
1. **Lokal utvikling**: Installer Python, Jupyter, Node.js lokalt
|
||||
2. **GitHub Codespaces**: Skybasert øyeblikkelig utviklingsmiljø
|
||||
3. **VS Code Dev Containers**: Lokalt containerbasert utvikling
|
||||
4. **Binder**: Start notebooks i skyen (hvis konfigurert)
|
||||
|
||||
### Retningslinjer for leksjonsinnhold
|
||||
- Hver leksjon er selvstendig, men bygger på tidligere konsepter
|
||||
- Quizer før leksjonen tester forkunnskaper
|
||||
- Quizer etter leksjonen forsterker læring
|
||||
- Oppgaver gir praktisk trening
|
||||
- Sketchnotes gir visuelle oppsummeringer
|
||||
|
||||
### Feilsøking av vanlige problemer
|
||||
|
||||
**Jupyter-kjerneproblemer:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm-installasjonsfeil:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Importfeil i notebooks:**
|
||||
- Verifiser at alle nødvendige biblioteker er installert
|
||||
- Sjekk Python-versjonskompatibilitet (Python 3.7+ anbefalt)
|
||||
- Sørg for at virtuelt miljø er aktivert
|
||||
|
||||
**Docsify laster ikke:**
|
||||
- Verifiser at du serverer fra repository-roten
|
||||
- Sjekk at `index.html` eksisterer
|
||||
- Sørg for riktig nettverkstilgang (port 3000)
|
||||
|
||||
### Ytelseshensyn
|
||||
- Store datasett kan ta tid å laste i notebooks
|
||||
- Visualiseringsrendering kan være treg for komplekse grafer
|
||||
- Vue.js utviklingsserver muliggjør hot-reload for rask iterasjon
|
||||
- Produksjonsbygg er optimalisert og minifisert
|
||||
|
||||
### Sikkerhetsnotater
|
||||
- Ingen sensitiv data eller legitimasjon skal legges inn
|
||||
- Bruk miljøvariabler for eventuelle API-nøkler i sky-leksjoner
|
||||
- Azure-relaterte leksjoner kan kreve Azure-kontolegitimasjon
|
||||
- Hold avhengigheter oppdatert for sikkerhetsoppdateringer
|
||||
|
||||
## Bidra til oversettelser
|
||||
- Automatiserte oversettelser administrert via GitHub Actions
|
||||
- Manuelle korrigeringer ønskes velkommen for oversettelsesnøyaktighet
|
||||
- Følg eksisterende oversettelsesmappe-struktur
|
||||
- Oppdater quiz-lenker for å inkludere språkparameter: `?loc=fr`
|
||||
- Test oversatte leksjoner for riktig visning
|
||||
|
||||
## Relaterte ressurser
|
||||
- Hovedpensum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Diskusjonsforum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Andre Microsoft-pensum: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Prosjektvedlikehold
|
||||
- Regelmessige oppdateringer for å holde innholdet aktuelt
|
||||
- Bidrag fra fellesskapet ønskes velkommen
|
||||
- Problemer spores på GitHub
|
||||
- PR-er gjennomgås av pensumansvarlige
|
||||
- Månedlige innholdsrevisjoner og oppdateringer
|
||||
|
||||
---
|
||||
|
||||
**Ansvarsfraskrivelse**:
|
||||
Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi tilstreber nøyaktighet, vær oppmerksom på at automatiserte oversettelser kan inneholde feil eller unøyaktigheter. Det originale dokumentet på sitt opprinnelige språk bør anses som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen.
|
||||
@ -0,0 +1,360 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:14:40+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "pa"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## ਪ੍ਰੋਜੈਕਟ ਝਲਕ
|
||||
|
||||
ਬਿਗਿਨਰਜ਼ ਲਈ ਡਾਟਾ ਸਾਇੰਸ ਮਾਈਕਰੋਸਾਫਟ ਐਜ਼ਯੂਰ ਕਲਾਉਡ ਐਡਵੋਕੇਟਸ ਦੁਆਰਾ ਬਣਾਈ ਗਈ 10 ਹਫ਼ਤਿਆਂ ਦੀ, 20 ਪਾਠਾਂ ਦੀ ਵਿਸਤ੍ਰਿਤ ਪਾਠਕ੍ਰਮ ਹੈ। ਇਹ ਰਿਪੋਜ਼ਟਰੀ ਇੱਕ ਸਿੱਖਣ ਦਾ ਸਰੋਤ ਹੈ ਜੋ ਪ੍ਰੋਜੈਕਟ-ਅਧਾਰਿਤ ਪਾਠਾਂ ਰਾਹੀਂ ਮੂਲ ਡਾਟਾ ਸਾਇੰਸ ਧਾਰਨਾਵਾਂ ਸਿਖਾਉਂਦਾ ਹੈ, ਜਿਸ ਵਿੱਚ Jupyter ਨੋਟਬੁੱਕ, ਇੰਟਰਐਕਟਿਵ ਕਵਿਜ਼, ਅਤੇ ਹੱਥ-ਅਨੁਭਵ ਅਸਾਈਨਮੈਂਟ ਸ਼ਾਮਲ ਹਨ।
|
||||
|
||||
**ਮੁੱਖ ਤਕਨਾਲੋਜੀਆਂ:**
|
||||
- **Jupyter ਨੋਟਬੁੱਕ**: Python 3 ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਮੁੱਖ ਸਿੱਖਣ ਮਾਧਿਅਮ
|
||||
- **Python ਲਾਇਬ੍ਰੇਰੀਆਂ**: pandas, numpy, matplotlib ਡਾਟਾ ਵਿਸ਼ਲੇਸ਼ਣ ਅਤੇ ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਲਈ
|
||||
- **Vue.js 2**: ਕਵਿਜ਼ ਐਪਲੀਕੇਸ਼ਨ (quiz-app ਫੋਲਡਰ)
|
||||
- **Docsify**: ਆਫਲਾਈਨ ਪਹੁੰਚ ਲਈ ਦਸਤਾਵੇਜ਼ ਸਾਈਟ ਜਨਰੇਟਰ
|
||||
- **Node.js/npm**: ਜਾਵਾਸਕ੍ਰਿਪਟ ਕੰਪੋਨੈਂਟਸ ਲਈ ਪੈਕੇਜ ਮੈਨੇਜਮੈਂਟ
|
||||
- **Markdown**: ਸਾਰੇ ਪਾਠ ਸਮੱਗਰੀ ਅਤੇ ਦਸਤਾਵੇਜ਼
|
||||
|
||||
**ਆਰਕੀਟੈਕਚਰ:**
|
||||
- ਬਹੁ-ਭਾਸ਼ਾਈ ਸਿੱਖਣ ਰਿਪੋਜ਼ਟਰੀ ਜਿਸ ਵਿੱਚ ਵਿਸਤ੍ਰਿਤ ਅਨੁਵਾਦ ਹਨ
|
||||
- ਪਾਠ ਮੋਡੀਊਲਾਂ ਵਿੱਚ ਸੰਰਚਿਤ (1-Introduction ਤੋਂ 6-Data-Science-In-Wild)
|
||||
- ਹਰ ਪਾਠ ਵਿੱਚ README, ਨੋਟਬੁੱਕ, ਅਸਾਈਨਮੈਂਟ ਅਤੇ ਕਵਿਜ਼ ਸ਼ਾਮਲ ਹਨ
|
||||
- ਪਾਠ ਤੋਂ ਪਹਿਲਾਂ/ਬਾਅਦ ਦੇ ਮੁਲਾਂਕਣ ਲਈ ਸਵਤੰਤਰ Vue.js ਕਵਿਜ਼ ਐਪਲੀਕੇਸ਼ਨ
|
||||
- GitHub Codespaces ਅਤੇ VS Code dev ਕੰਟੇਨਰ ਸਹਾਇਤਾ
|
||||
|
||||
## ਸੈਟਅੱਪ ਕਮਾਂਡ
|
||||
|
||||
### ਰਿਪੋਜ਼ਟਰੀ ਸੈਟਅੱਪ
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python ਵਾਤਾਵਰਣ ਸੈਟਅੱਪ
|
||||
```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
|
||||
```
|
||||
|
||||
### ਕਵਿਜ਼ ਐਪਲੀਕੇਸ਼ਨ ਸੈਟਅੱਪ
|
||||
```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 ਦਸਤਾਵੇਜ਼ ਸਰਵਰ
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਪ੍ਰੋਜੈਕਟ ਸੈਟਅੱਪ
|
||||
ਜਿਵੇਂ ਕਿ meaningful-visualizations (lesson 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
|
||||
```
|
||||
|
||||
|
||||
## ਵਿਕਾਸ ਵਰਕਫਲੋ
|
||||
|
||||
### Jupyter ਨੋਟਬੁੱਕ ਨਾਲ ਕੰਮ ਕਰਨਾ
|
||||
1. ਰਿਪੋਜ਼ਟਰੀ ਰੂਟ ਵਿੱਚ Jupyter ਸ਼ੁਰੂ ਕਰੋ: `jupyter notebook`
|
||||
2. ਚਾਹੀਦੇ ਪਾਠ ਫੋਲਡਰ ਵਿੱਚ ਜਾਓ
|
||||
3. `.ipynb` ਫਾਈਲਾਂ ਖੋਲ੍ਹੋ ਅਤੇ ਅਭਿਆਸ ਕਰੋ
|
||||
4. ਨੋਟਬੁੱਕ ਵਿੱਚ ਵਿਆਖਿਆਵਾਂ ਅਤੇ ਕੋਡ ਸੈੱਲਾਂ ਸ਼ਾਮਲ ਹਨ
|
||||
5. ਜ਼ਿਆਦਾਤਰ ਨੋਟਬੁੱਕ 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)
|
||||
|
||||
## ਟੈਸਟਿੰਗ ਨਿਰਦੇਸ਼
|
||||
|
||||
### ਕਵਿਜ਼ ਐਪਲੀਕੇਸ਼ਨ ਟੈਸਟਿੰਗ
|
||||
```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
|
||||
```
|
||||
|
||||
### ਨੋਟਬੁੱਕ ਟੈਸਟਿੰਗ
|
||||
- ਨੋਟਬੁੱਕ ਲਈ ਕੋਈ ਆਟੋਮੈਟਿਕ ਟੈਸਟ ਫਰੇਮਵਰਕ ਨਹੀਂ ਹੈ
|
||||
- ਮੈਨੂਅਲ ਵੈਰੀਫਿਕੇਸ਼ਨ: ਸਾਰੇ ਸੈੱਲ ਲਗਾਤਾਰ ਚਲਾਓ ਅਤੇ ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਕੋਈ ਗਲਤੀ ਨਹੀਂ ਹੈ
|
||||
- ਡਾਟਾ ਫਾਈਲਾਂ ਪਹੁੰਚਯੋਗ ਹਨ ਅਤੇ ਆਉਟਪੁੱਟ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਜਨਰੇਟ ਹੁੰਦੀ ਹੈ
|
||||
- ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਰੈਂਡਰ ਹੁੰਦੇ ਹਨ
|
||||
|
||||
### ਦਸਤਾਵੇਜ਼ ਟੈਸਟਿੰਗ
|
||||
```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
|
||||
```
|
||||
|
||||
### ਕੋਡ ਗੁਣਵੱਤਾ ਚੈੱਕ
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## ਕੋਡ ਸਟਾਈਲ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼
|
||||
|
||||
### Python (Jupyter ਨੋਟਬੁੱਕ)
|
||||
- Python ਕੋਡ ਲਈ PEP 8 ਸਟਾਈਲ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼ਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ
|
||||
- ਸਪਸ਼ਟ ਵੈਰੀਏਬਲ ਨਾਮ ਵਰਤੋ ਜੋ ਡਾਟਾ ਨੂੰ ਵਿਆਖਿਆ ਕਰਦੇ ਹਨ
|
||||
- ਕੋਡ ਸੈੱਲਾਂ ਤੋਂ ਪਹਿਲਾਂ ਵਿਆਖਿਆਵਾਂ ਵਾਲੇ ਮਾਰਕਡਾਊਨ ਸੈੱਲ ਸ਼ਾਮਲ ਕਰੋ
|
||||
- ਕੋਡ ਸੈੱਲਾਂ ਨੂੰ ਇੱਕਲੇ ਧਾਰਨਾ ਜਾਂ ਕਾਰਵਾਈ 'ਤੇ ਕੇਂਦਰਿਤ ਰੱਖੋ
|
||||
- pandas ਡਾਟਾ ਮੈਨਿਪੂਲੇਸ਼ਨ ਲਈ, matplotlib ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਲਈ ਵਰਤੋ
|
||||
- ਆਮ ਇੰਪੋਰਟ ਪੈਟਰਨ:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Vue.js 2 ਸਟਾਈਲ ਗਾਈਡ ਅਤੇ ਬਿਹਤਰ ਅਭਿਆਸਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ
|
||||
- ESLint ਕਨਫਿਗਰੇਸ਼ਨ `quiz-app/package.json` ਵਿੱਚ
|
||||
- Vue ਸਿੰਗਲ-ਫਾਈਲ ਕੰਪੋਨੈਂਟ (.vue ਫਾਈਲਾਂ) ਵਰਤੋ
|
||||
- ਕੰਪੋਨੈਂਟ-ਅਧਾਰਿਤ ਆਰਕੀਟੈਕਚਰ ਨੂੰ ਬਣਾਓ
|
||||
- ਬਦਲਣ ਤੋਂ ਪਹਿਲਾਂ `npm run lint` ਚਲਾਓ
|
||||
|
||||
### Markdown ਦਸਤਾਵੇਜ਼
|
||||
- ਸਪਸ਼ਟ ਹੈਡਿੰਗ ਹਾਇਰਾਰਕੀ (# ## ### ਆਦਿ) ਵਰਤੋ
|
||||
- ਭਾਸ਼ਾ ਨਿਰਧਾਰਕਾਂ ਨਾਲ ਕੋਡ ਬਲਾਕ ਸ਼ਾਮਲ ਕਰੋ
|
||||
- ਚਿੱਤਰਾਂ ਲਈ alt ਟੈਕਸਟ ਸ਼ਾਮਲ ਕਰੋ
|
||||
- ਸੰਬੰਧਿਤ ਪਾਠਾਂ ਅਤੇ ਸਰੋਤਾਂ ਨਾਲ ਲਿੰਕ ਕਰੋ
|
||||
- ਪੜ੍ਹਨਯੋਗਤਾ ਲਈ ਲਾਈਨ ਦੀ ਲੰਬਾਈ ਵਾਜਬ ਰੱਖੋ
|
||||
|
||||
### ਫਾਈਲ ਸੰਰਚਨਾ
|
||||
- ਪਾਠ ਸਮੱਗਰੀ ਗਿਣਤੀ ਫੋਲਡਰਾਂ ਵਿੱਚ (01-defining-data-science, ਆਦਿ)
|
||||
- ਹੱਲਾਂ ਸਮਰਪਿਤ `solution/` ਸਬਫੋਲਡਰਾਂ ਵਿੱਚ
|
||||
- ਅਨੁਵਾਦ `translations/` ਫੋਲਡਰ ਵਿੱਚ ਅੰਗਰੇਜ਼ੀ ਸੰਰਚਨਾ ਨੂੰ ਮਿਰਰ ਕਰਦੇ ਹਨ
|
||||
- ਡਾਟਾ ਫਾਈਲਾਂ `data/` ਜਾਂ ਪਾਠ-ਵਿਸ਼ੇਸ਼ ਫੋਲਡਰਾਂ ਵਿੱਚ ਰੱਖੋ
|
||||
|
||||
## ਬਿਲਡ ਅਤੇ ਡਿਪਲੌਇਮੈਂਟ
|
||||
|
||||
### ਕਵਿਜ਼ ਐਪਲੀਕੇਸ਼ਨ ਡਿਪਲੌਇਮੈਂਟ
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps ਡਿਪਲੌਇਮੈਂਟ
|
||||
ਕਵਿਜ਼-ਐਪ ਨੂੰ Azure Static Web Apps 'ਤੇ ਡਿਪਲੌਇ ਕੀਤਾ ਜਾ ਸਕਦਾ ਹੈ:
|
||||
1. Azure Static Web App ਸਰੋਤ ਬਣਾਓ
|
||||
2. GitHub ਰਿਪੋਜ਼ਟਰੀ ਨਾਲ ਕਨੈਕਟ ਕਰੋ
|
||||
3. ਬਿਲਡ ਸੈਟਿੰਗਾਂ ਕਨਫਿਗਰ ਕਰੋ:
|
||||
- ਐਪ ਸਥਾਨ: `quiz-app`
|
||||
- ਆਉਟਪੁੱਟ ਸਥਾਨ: `dist`
|
||||
4. GitHub Actions ਵਰਕਫਲੋ ਪੁਸ਼ 'ਤੇ ਆਟੋ-ਡਿਪਲੌਇ ਕਰੇਗਾ
|
||||
|
||||
### ਦਸਤਾਵੇਜ਼ ਸਾਈਟ
|
||||
```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
|
||||
- ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ dev ਕੰਟੇਨਰ ਕਨਫਿਗਰੇਸ਼ਨ ਸ਼ਾਮਲ ਹੈ
|
||||
- Codespaces ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ Python ਅਤੇ Node.js ਵਾਤਾਵਰਣ ਸੈਟਅੱਪ ਕਰਦਾ ਹੈ
|
||||
- GitHub UI ਰਾਹੀਂ ਰਿਪੋਜ਼ਟਰੀ ਨੂੰ Codespace ਵਿੱਚ ਖੋਲ੍ਹੋ
|
||||
- ਸਾਰੇ ਡਿਪੈਂਡੈਂਸੀਜ਼ ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਇੰਸਟਾਲ ਹੁੰਦੀਆਂ ਹਨ
|
||||
|
||||
## ਪੁਲ ਰਿਕਵੈਸਟ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼
|
||||
|
||||
### ਸਬਮਿਟ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### PR ਟਾਈਟਲ ਫਾਰਮੈਟ
|
||||
- ਸਪਸ਼ਟ, ਵਰਣਨਾਤਮਕ ਟਾਈਟਲ ਵਰਤੋ
|
||||
- ਫਾਰਮੈਟ: `[Component] Brief description`
|
||||
- ਉਦਾਹਰਣ:
|
||||
- `[Lesson 7] Fix Python notebook import error`
|
||||
- `[Quiz App] Add German translation`
|
||||
- `[Docs] Update README with new prerequisites`
|
||||
|
||||
### ਲਾਜ਼ਮੀ ਚੈੱਕ
|
||||
- ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਸਾਰਾ ਕੋਡ ਗਲਤੀ ਤੋਂ ਬਿਨਾਂ ਚਲਦਾ ਹੈ
|
||||
- ਨੋਟਬੁੱਕ ਪੂਰੀ ਤਰ੍ਹਾਂ ਚਲਾਉਣ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ
|
||||
- Vue.js ਐਪਸ ਸਫਲਤਾਪੂਰਵਕ ਬਣਾਉਣ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ
|
||||
- ਦਸਤਾਵੇਜ਼ ਲਿੰਕਾਂ ਦੀ ਜਾਂਚ ਕਰੋ
|
||||
- ਜੇਕਰ ਸੋਧ ਕੀਤੀ ਗਈ ਹੈ ਤਾਂ ਕਵਿਜ਼ ਐਪਲੀਕੇਸ਼ਨ ਟੈਸਟ ਕਰੋ
|
||||
- ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਅਨੁਵਾਦ ਸੰਰਚਨਾ ਸਥਿਰ ਹੈ
|
||||
|
||||
### ਯੋਗਦਾਨ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼
|
||||
- ਮੌਜੂਦਾ ਕੋਡ ਸਟਾਈਲ ਅਤੇ ਪੈਟਰਨ ਦੀ ਪਾਲਣਾ ਕਰੋ
|
||||
- ਜਟਿਲ ਲਾਜ਼ਿਕ ਲਈ ਵਿਆਖਿਆਵਾਂ ਵਾਲੇ ਟਿੱਪਣੀਆਂ ਸ਼ਾਮਲ ਕਰੋ
|
||||
- ਸੰਬੰਧਿਤ ਦਸਤਾਵੇਜ਼ ਅਪਡੇਟ ਕਰੋ
|
||||
- ਜੇਕਰ ਲਾਗੂ ਹੋਵੇ ਤਾਂ ਵੱਖ-ਵੱਖ ਪਾਠ ਮੋਡੀਊਲਾਂ 'ਤੇ ਬਦਲਾਵਾਂ ਟੈਸਟ ਕਰੋ
|
||||
- CONTRIBUTING.md ਫਾਈਲ ਦੀ ਸਮੀਖਿਆ ਕਰੋ
|
||||
|
||||
## ਵਾਧੂ ਨੋਟਸ
|
||||
|
||||
### ਆਮ ਲਾਇਬ੍ਰੇਰੀਆਂ ਦੀ ਵਰਤੋਂ
|
||||
- **pandas**: ਡਾਟਾ ਮੈਨਿਪੂਲੇਸ਼ਨ ਅਤੇ ਵਿਸ਼ਲੇਸ਼ਣ
|
||||
- **numpy**: ਗਣਿਤੀ ਗਣਨਾ
|
||||
- **matplotlib**: ਡਾਟਾ ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਅਤੇ ਪਲਾਟਿੰਗ
|
||||
- **seaborn**: ਸਾਂਖਿਕ ਡਾਟਾ ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ (ਕੁਝ ਪਾਠਾਂ ਵਿੱਚ)
|
||||
- **scikit-learn**: ਮਸ਼ੀਨ ਲਰਨਿੰਗ (ਉੱਚ ਪੱਧਰ ਦੇ ਪਾਠ)
|
||||
|
||||
### ਡਾਟਾ ਫਾਈਲਾਂ ਨਾਲ ਕੰਮ ਕਰਨਾ
|
||||
- ਡਾਟਾ ਫਾਈਲਾਂ `data/` ਫੋਲਡਰ ਜਾਂ ਪਾਠ-ਵਿਸ਼ੇਸ਼ ਡਾਇਰੈਕਟਰੀਜ਼ ਵਿੱਚ ਸਥਿਤ ਹਨ
|
||||
- ਜ਼ਿਆਦਾਤਰ ਨੋਟਬੁੱਕ ਡਾਟਾ ਫਾਈਲਾਂ ਨੂੰ ਰਿਲੇਟਿਵ ਪਾਥ ਵਿੱਚ ਉਮੀਦ ਕਰਦੇ ਹਨ
|
||||
- CSV ਫਾਈਲਾਂ ਮੁੱਖ ਡਾਟਾ ਫਾਰਮੈਟ ਹਨ
|
||||
- ਕੁਝ ਪਾਠ JSON ਨੂੰ ਗੈਰ-ਸੰਬੰਧਿਤ ਡਾਟਾ ਉਦਾਹਰਣਾਂ ਲਈ ਵਰਤਦੇ ਹਨ
|
||||
|
||||
### ਬਹੁਭਾਸ਼ਾਈ ਸਹਾਇਤਾ
|
||||
- 40+ ਭਾਸ਼ਾ ਅਨੁਵਾਦ GitHub Actions ਰਾਹੀਂ ਆਟੋਮੈਟਿਕ
|
||||
- ਅਨੁਵਾਦ ਵਰਕਫਲੋ `.github/workflows/co-op-translator.yml` ਵਿੱਚ
|
||||
- ਅਨੁਵਾਦ `translations/` ਫੋਲਡਰ ਵਿੱਚ ਭਾਸ਼ਾ ਕੋਡਾਂ ਨਾਲ
|
||||
- ਕਵਿਜ਼ ਅਨੁਵਾਦ `quiz-app/src/assets/translations/` ਵਿੱਚ
|
||||
|
||||
### ਵਿਕਾਸ ਵਾਤਾਵਰਣ ਵਿਕਲਪ
|
||||
1. **ਸਥਾਨਕ ਵਿਕਾਸ**: ਸਥਾਨਕ ਤੌਰ 'ਤੇ Python, Jupyter, Node.js ਇੰਸਟਾਲ ਕਰੋ
|
||||
2. **GitHub Codespaces**: ਕਲਾਉਡ-ਅਧਾਰਿਤ ਤੁਰੰਤ ਵਿਕਾਸ ਵਾਤਾਵਰਣ
|
||||
3. **VS Code Dev Containers**: ਸਥਾਨਕ ਕੰਟੇਨਰ-ਅਧਾਰਿਤ ਵਿਕਾਸ
|
||||
4. **Binder**: ਕਲਾਉਡ ਵਿੱਚ ਨੋਟਬੁੱਕ ਲਾਂਚ ਕਰੋ (ਜੇਕਰ ਕਨਫਿਗਰ ਕੀਤਾ ਗਿਆ)
|
||||
|
||||
### ਪਾਠ ਸਮੱਗਰੀ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼
|
||||
- ਹਰ ਪਾਠ ਸਵਤੰਤਰ ਹੈ ਪਰ ਪਿਛਲੇ ਧਾਰਨਾਵਾਂ 'ਤੇ ਬਣਦਾ ਹੈ
|
||||
- ਪਾਠ ਤੋਂ ਪਹਿਲਾਂ ਕਵਿਜ਼ ਪਿਛਲੇ ਗਿਆਨ ਦੀ ਜਾਂਚ ਕਰਦੇ ਹਨ
|
||||
- ਪਾਠ ਤੋਂ ਬਾਅਦ ਕਵਿਜ਼ ਸਿੱਖਣ ਨੂੰ ਮਜ਼ਬੂਤ ਕਰਦੇ ਹਨ
|
||||
- ਅਸਾਈਨਮੈਂਟ ਹੱਥ-ਅਨੁਭਵ ਅਭਿਆਸ ਪ੍ਰਦਾਨ ਕਰਦੇ ਹਨ
|
||||
- ਸਕੈਚਨੋਟਸ ਵਿਜ਼ੁਅਲ ਸੰਖੇਪ ਪ੍ਰਦਾਨ ਕਰਦੇ ਹਨ
|
||||
|
||||
### ਆਮ ਸਮੱਸਿਆਵਾਂ ਦਾ ਨਿਪਟਾਰਾ
|
||||
|
||||
**Jupyter Kernel ਸਮੱਸਿਆਵਾਂ:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm ਇੰਸਟਾਲ ਫੇਲ੍ਹ:**
|
||||
```bash
|
||||
# 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 dev ਸਰਵਰ ਤੇਜ਼ ਦੁਹਰਾਈ ਲਈ ਹੌਟ-ਰੀਲੋਡ ਸਹਾਇਤਾ ਦਿੰਦਾ ਹੈ
|
||||
- ਪ੍ਰੋਡਕਸ਼ਨ ਬਿਲਡਸ ਅਨੁਕੂਲਿਤ ਅਤੇ ਮਿਨੀਫਾਈਡ ਹੁੰਦੇ ਹਨ
|
||||
|
||||
### ਸੁਰੱਖਿਆ ਨੋਟਸ
|
||||
- ਕੋਈ ਸੰਵੇਦਨਸ਼ੀਲ ਡਾਟਾ ਜਾਂ ਪ੍ਰਮਾਣ ਪੱਤਰ ਕਮਿਟ ਨਹੀਂ ਕੀਤਾ ਜਾਣਾ ਚਾਹੀਦਾ
|
||||
- ਕਲਾਉਡ ਪਾਠਾਂ ਵਿੱਚ ਕੋਈ ਵੀ API ਕੁੰਜੀਆਂ ਲਈ ਵਾਤਾਵਰਣ ਵੈਰੀਏਬਲ ਵਰਤੋ
|
||||
- Azure-ਸੰਬੰਧਿਤ ਪਾਠਾਂ ਨੂੰ Azure ਖਾਤੇ ਦੇ ਪ੍ਰਮਾਣ ਪੱਤਰਾਂ ਦੀ ਲੋੜ ਹੋ ਸਕਦੀ ਹੈ
|
||||
- ਸੁਰੱਖਿਆ ਪੈਚਾਂ ਲਈ ਡਿਪੈਂਡੈਂਸੀਜ਼ ਨੂੰ ਅਪਡੇਟ ਰੱਖੋ
|
||||
|
||||
## ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਯੋਗਦਾਨ
|
||||
- GitHub Actions ਰਾਹੀਂ ਆਟੋਮੈਟਿਕ ਅਨੁਵਾਦ ਪ੍ਰਬੰਧਿਤ
|
||||
- ਅਨੁਵਾਦ ਸਹੀਤਾ ਲਈ ਮੈਨੂਅਲ ਸੁਧਾਰਾਂ ਦਾ ਸਵਾਗਤ ਹੈ
|
||||
- ਮੌਜੂਦਾ ਅਨੁਵਾਦ ਫੋਲਡਰ ਸੰਰਚਨਾ ਦੀ ਪਾਲਣਾ ਕਰੋ
|
||||
- ਕਵਿਜ਼ ਲਿੰਕਾਂ ਨੂੰ ਭਾਸ਼ਾ ਪੈਰਾਮੀਟਰ ਸ਼ਾਮਲ ਕਰਨ ਲਈ ਅਪਡੇਟ
|
||||
|
||||
---
|
||||
|
||||
**ਅਸਵੀਕਰਤੀ**:
|
||||
ਇਹ ਦਸਤਾਵੇਜ਼ AI ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਅਨੁਵਾਦ ਕੀਤਾ ਗਿਆ ਹੈ। ਹਾਲਾਂਕਿ ਅਸੀਂ ਸਹੀ ਹੋਣ ਦਾ ਯਤਨ ਕਰਦੇ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਦਿਓ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸੁਚਤਤਾਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਇਸ ਦੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਮੌਜੂਦ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਅਧਿਕਾਰਤ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਮਹੱਤਵਪੂਰਨ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੇ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆ ਲਈ ਅਸੀਂ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ।
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:19:07+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "pl"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Przegląd projektu
|
||||
|
||||
Data Science for Beginners to kompleksowy, 10-tygodniowy kurs składający się z 20 lekcji, stworzony przez Microsoft Azure Cloud Advocates. Repozytorium jest zasobem edukacyjnym, który uczy podstawowych pojęć z zakresu nauki o danych poprzez lekcje oparte na projektach, w tym notatniki Jupyter, interaktywne quizy i zadania praktyczne.
|
||||
|
||||
**Kluczowe technologie:**
|
||||
- **Notatniki Jupyter**: Główne medium nauki z użyciem Python 3
|
||||
- **Biblioteki Python**: pandas, numpy, matplotlib do analizy danych i wizualizacji
|
||||
- **Vue.js 2**: Aplikacja quizowa (folder quiz-app)
|
||||
- **Docsify**: Generator strony dokumentacji do użytku offline
|
||||
- **Node.js/npm**: Zarządzanie pakietami dla komponentów JavaScript
|
||||
- **Markdown**: Cała treść lekcji i dokumentacja
|
||||
|
||||
**Architektura:**
|
||||
- Repozytorium edukacyjne w wielu językach z obszernymi tłumaczeniami
|
||||
- Struktura podzielona na moduły lekcji (1-Introduction do 6-Data-Science-In-Wild)
|
||||
- Każda lekcja zawiera README, notatniki, zadania i quizy
|
||||
- Samodzielna aplikacja quizowa Vue.js do oceny przed/po lekcji
|
||||
- Wsparcie dla GitHub Codespaces i kontenerów deweloperskich VS Code
|
||||
|
||||
## Polecenia konfiguracji
|
||||
|
||||
### Konfiguracja repozytorium
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Konfiguracja środowiska Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Konfiguracja aplikacji quizowej
|
||||
```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
|
||||
```
|
||||
|
||||
### Serwer dokumentacji Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Konfiguracja projektów wizualizacyjnych
|
||||
Dla projektów wizualizacyjnych, takich jak meaningful-visualizations (lekcja 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
|
||||
```
|
||||
|
||||
|
||||
## Przebieg pracy deweloperskiej
|
||||
|
||||
### Praca z notatnikami Jupyter
|
||||
1. Uruchom Jupyter w katalogu głównym repozytorium: `jupyter notebook`
|
||||
2. Przejdź do odpowiedniego folderu lekcji
|
||||
3. Otwórz pliki `.ipynb`, aby przejść przez ćwiczenia
|
||||
4. Notatniki są samodzielne, zawierają wyjaśnienia i komórki kodu
|
||||
5. Większość notatników używa pandas, numpy i matplotlib - upewnij się, że są zainstalowane
|
||||
|
||||
### Struktura lekcji
|
||||
Każda lekcja zazwyczaj zawiera:
|
||||
- `README.md` - Główna treść lekcji z teorią i przykładami
|
||||
- `notebook.ipynb` - Ćwiczenia praktyczne w notatniku Jupyter
|
||||
- `assignment.ipynb` lub `assignment.md` - Zadania praktyczne
|
||||
- Folder `solution/` - Notatniki z rozwiązaniami i kod
|
||||
- Folder `images/` - Materiały wizualne wspierające
|
||||
|
||||
### Rozwój aplikacji quizowej
|
||||
- Aplikacja Vue.js 2 z funkcją hot-reload podczas rozwoju
|
||||
- Quizy przechowywane w `quiz-app/src/assets/translations/`
|
||||
- Każdy język ma własny folder tłumaczeń (en, fr, es, itd.)
|
||||
- Numeracja quizów zaczyna się od 0 i kończy na 39 (łącznie 40 quizów)
|
||||
|
||||
### Dodawanie tłumaczeń
|
||||
- Tłumaczenia umieszczane w folderze `translations/` w katalogu głównym repozytorium
|
||||
- Każdy język ma pełną strukturę lekcji odzwierciedloną z angielskiego
|
||||
- Automatyczne tłumaczenie za pomocą GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instrukcje testowania
|
||||
|
||||
### Testowanie aplikacji quizowej
|
||||
```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
|
||||
```
|
||||
|
||||
### Testowanie notatników
|
||||
- Nie istnieje automatyczny framework testowy dla notatników
|
||||
- Walidacja ręczna: Uruchom wszystkie komórki w kolejności, aby upewnić się, że nie ma błędów
|
||||
- Sprawdź dostępność plików danych i poprawność generowanych wyników
|
||||
- Upewnij się, że wizualizacje renderują się poprawnie
|
||||
|
||||
### Testowanie dokumentacji
|
||||
```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
|
||||
```
|
||||
|
||||
### Kontrola jakości kodu
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Wytyczne dotyczące stylu kodu
|
||||
|
||||
### Python (Notatniki Jupyter)
|
||||
- Przestrzegaj wytycznych stylu PEP 8 dla kodu Python
|
||||
- Używaj jasnych nazw zmiennych, które opisują analizowane dane
|
||||
- Dodawaj komórki markdown z wyjaśnieniami przed komórkami kodu
|
||||
- Skup komórki kodu na pojedynczych koncepcjach lub operacjach
|
||||
- Używaj pandas do manipulacji danymi, matplotlib do wizualizacji
|
||||
- Typowy wzorzec importu:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Przestrzegaj wytycznych stylu Vue.js 2 i najlepszych praktyk
|
||||
- Konfiguracja ESLint w `quiz-app/package.json`
|
||||
- Używaj komponentów Vue w pojedynczych plikach (.vue)
|
||||
- Utrzymuj architekturę opartą na komponentach
|
||||
- Uruchom `npm run lint` przed zatwierdzeniem zmian
|
||||
|
||||
### Dokumentacja Markdown
|
||||
- Używaj jasnej hierarchii nagłówków (# ## ### itd.)
|
||||
- Dodawaj bloki kodu ze specyfikatorami języka
|
||||
- Dodawaj tekst alternatywny dla obrazów
|
||||
- Linkuj do powiązanych lekcji i zasobów
|
||||
- Zachowaj rozsądną długość linii dla czytelności
|
||||
|
||||
### Organizacja plików
|
||||
- Treść lekcji w ponumerowanych folderach (01-defining-data-science, itd.)
|
||||
- Rozwiązania w dedykowanych podfolderach `solution/`
|
||||
- Tłumaczenia odzwierciedlają strukturę angielską w folderze `translations/`
|
||||
- Pliki danych w folderze `data/` lub specyficznych dla lekcji
|
||||
|
||||
## Budowa i wdrożenie
|
||||
|
||||
### Wdrożenie aplikacji quizowej
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Wdrożenie Azure Static Web Apps
|
||||
Aplikacja quizowa może być wdrożona na Azure Static Web Apps:
|
||||
1. Utwórz zasób Azure Static Web App
|
||||
2. Połącz z repozytorium GitHub
|
||||
3. Skonfiguruj ustawienia budowy:
|
||||
- Lokalizacja aplikacji: `quiz-app`
|
||||
- Lokalizacja wynikowa: `dist`
|
||||
4. Workflow GitHub Actions automatycznie wdroży zmiany po ich przesłaniu
|
||||
|
||||
### Strona dokumentacji
|
||||
```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
|
||||
- Repozytorium zawiera konfigurację kontenera deweloperskiego
|
||||
- Codespaces automatycznie konfiguruje środowisko Python i Node.js
|
||||
- Otwórz repozytorium w Codespace za pomocą interfejsu GitHub
|
||||
- Wszystkie zależności instalują się automatycznie
|
||||
|
||||
## Wytyczne dotyczące pull requestów
|
||||
|
||||
### Przed przesłaniem
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format tytułu PR
|
||||
- Używaj jasnych, opisowych tytułów
|
||||
- Format: `[Komponent] Krótki opis`
|
||||
- Przykłady:
|
||||
- `[Lekcja 7] Napraw błąd importu w notatniku Python`
|
||||
- `[Aplikacja Quizowa] Dodaj tłumaczenie na niemiecki`
|
||||
- `[Dokumentacja] Zaktualizuj README o nowe wymagania wstępne`
|
||||
|
||||
### Wymagane kontrole
|
||||
- Upewnij się, że cały kod działa bez błędów
|
||||
- Zweryfikuj, że notatniki wykonują się w całości
|
||||
- Potwierdź, że aplikacje Vue.js budują się poprawnie
|
||||
- Sprawdź, czy linki w dokumentacji działają
|
||||
- Przetestuj aplikację quizową, jeśli została zmodyfikowana
|
||||
- Zweryfikuj, że tłumaczenia zachowują spójną strukturę
|
||||
|
||||
### Wytyczne dotyczące wkładu
|
||||
- Przestrzegaj istniejącego stylu kodu i wzorców
|
||||
- Dodawaj wyjaśniające komentarze dla złożonej logiki
|
||||
- Aktualizuj odpowiednią dokumentację
|
||||
- Testuj zmiany w różnych modułach lekcji, jeśli to możliwe
|
||||
- Przejrzyj plik CONTRIBUTING.md
|
||||
|
||||
## Dodatkowe uwagi
|
||||
|
||||
### Często używane biblioteki
|
||||
- **pandas**: Manipulacja i analiza danych
|
||||
- **numpy**: Obliczenia numeryczne
|
||||
- **matplotlib**: Wizualizacja danych i wykresy
|
||||
- **seaborn**: Wizualizacja danych statystycznych (niektóre lekcje)
|
||||
- **scikit-learn**: Uczenie maszynowe (lekcje zaawansowane)
|
||||
|
||||
### Praca z plikami danych
|
||||
- Pliki danych znajdują się w folderze `data/` lub w katalogach specyficznych dla lekcji
|
||||
- Większość notatników oczekuje plików danych w ścieżkach względnych
|
||||
- Pliki CSV są głównym formatem danych
|
||||
- Niektóre lekcje używają JSON dla przykładów danych nierelacyjnych
|
||||
|
||||
### Wsparcie wielojęzyczne
|
||||
- Ponad 40 tłumaczeń językowych za pomocą automatycznych GitHub Actions
|
||||
- Workflow tłumaczeń w `.github/workflows/co-op-translator.yml`
|
||||
- Tłumaczenia w folderze `translations/` z kodami języków
|
||||
- Tłumaczenia quizów w `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opcje środowiska deweloperskiego
|
||||
1. **Rozwój lokalny**: Zainstaluj Python, Jupyter, Node.js lokalnie
|
||||
2. **GitHub Codespaces**: Środowisko rozwoju w chmurze
|
||||
3. **Kontenery deweloperskie VS Code**: Lokalny rozwój oparty na kontenerach
|
||||
4. **Binder**: Uruchamianie notatników w chmurze (jeśli skonfigurowane)
|
||||
|
||||
### Wytyczne dotyczące treści lekcji
|
||||
- Każda lekcja jest samodzielna, ale buduje na poprzednich koncepcjach
|
||||
- Quizy przed lekcją sprawdzają wcześniejszą wiedzę
|
||||
- Quizy po lekcji wzmacniają naukę
|
||||
- Zadania zapewniają praktykę
|
||||
- Sketchnotes oferują wizualne podsumowania
|
||||
|
||||
### Rozwiązywanie typowych problemów
|
||||
|
||||
**Problemy z Jupyter Kernel:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Problemy z instalacją npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Błędy importu w notatnikach:**
|
||||
- Upewnij się, że wszystkie wymagane biblioteki są zainstalowane
|
||||
- Sprawdź zgodność wersji Python (zalecany Python 3.7+)
|
||||
- Upewnij się, że środowisko wirtualne jest aktywowane
|
||||
|
||||
**Docsify nie ładuje się:**
|
||||
- Upewnij się, że serwujesz z katalogu głównego repozytorium
|
||||
- Sprawdź, czy istnieje plik `index.html`
|
||||
- Upewnij się, że masz odpowiedni dostęp do sieci (port 3000)
|
||||
|
||||
### Uwagi dotyczące wydajności
|
||||
- Duże zestawy danych mogą długo się ładować w notatnikach
|
||||
- Renderowanie wizualizacji może być wolne dla złożonych wykresów
|
||||
- Serwer deweloperski Vue.js umożliwia szybkie iteracje dzięki hot-reload
|
||||
- Kompilacje produkcyjne są zoptymalizowane i zminimalizowane
|
||||
|
||||
### Uwagi dotyczące bezpieczeństwa
|
||||
- Nie należy przesyłać danych wrażliwych ani poświadczeń
|
||||
- Używaj zmiennych środowiskowych dla kluczy API w lekcjach chmurowych
|
||||
- Lekcje związane z Azure mogą wymagać poświadczeń konta Azure
|
||||
- Aktualizuj zależności dla poprawek bezpieczeństwa
|
||||
|
||||
## Wkład w tłumaczenia
|
||||
- Automatyczne tłumaczenia zarządzane za pomocą GitHub Actions
|
||||
- Mile widziane ręczne poprawki dla dokładności tłumaczeń
|
||||
- Przestrzegaj istniejącej struktury folderów tłumaczeń
|
||||
- Aktualizuj linki do quizów, aby zawierały parametr języka: `?loc=fr`
|
||||
- Testuj przetłumaczone lekcje pod kątem poprawnego renderowania
|
||||
|
||||
## Powiązane zasoby
|
||||
- Główna ścieżka nauczania: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum dyskusyjne: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Inne kursy Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Utrzymanie projektu
|
||||
- Regularne aktualizacje, aby treść była aktualna
|
||||
- Mile widziane wkłady społeczności
|
||||
- Problemy śledzone na GitHub
|
||||
- PR-y przeglądane przez opiekunów programu nauczania
|
||||
- Miesięczne przeglądy i aktualizacje treści
|
||||
|
||||
---
|
||||
|
||||
**Zastrzeżenie**:
|
||||
Ten dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Chociaż staramy się zapewnić dokładność, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w jego rodzimym języku powinien być uznawany za źródło autorytatywne. W przypadku informacji krytycznych zaleca się skorzystanie z profesjonalnego tłumaczenia przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:15:58+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "pt"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Visão Geral do Projeto
|
||||
|
||||
Data Science for Beginners é um currículo abrangente de 10 semanas e 20 lições, criado pelos Microsoft Azure Cloud Advocates. Este repositório é um recurso de aprendizagem que ensina conceitos fundamentais de ciência de dados através de lições baseadas em projetos, incluindo notebooks Jupyter, questionários interativos e tarefas práticas.
|
||||
|
||||
**Principais Tecnologias:**
|
||||
- **Jupyter Notebooks**: Meio principal de aprendizagem utilizando Python 3
|
||||
- **Bibliotecas Python**: pandas, numpy, matplotlib para análise e visualização de dados
|
||||
- **Vue.js 2**: Aplicação de questionários (pasta quiz-app)
|
||||
- **Docsify**: Gerador de sites de documentação para acesso offline
|
||||
- **Node.js/npm**: Gestão de pacotes para componentes JavaScript
|
||||
- **Markdown**: Todo o conteúdo das lições e documentação
|
||||
|
||||
**Arquitetura:**
|
||||
- Repositório educacional multilíngue com extensas traduções
|
||||
- Estruturado em módulos de lições (1-Introdução até 6-Ciência-de-Dados-no-Mundo-Real)
|
||||
- Cada lição inclui README, notebooks, tarefas e questionários
|
||||
- Aplicação de questionários Vue.js independente para avaliações pré/pós-lição
|
||||
- Suporte para GitHub Codespaces e contêineres de desenvolvimento do VS Code
|
||||
|
||||
## Comandos de Configuração
|
||||
|
||||
### Configuração do Repositório
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Configuração do Ambiente Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Configuração da Aplicação de Questionários
|
||||
```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
|
||||
```
|
||||
|
||||
### Servidor de Documentação Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Configuração de Projetos de Visualização
|
||||
Para projetos de visualização como meaningful-visualizations (lição 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
|
||||
```
|
||||
|
||||
|
||||
## Fluxo de Trabalho de Desenvolvimento
|
||||
|
||||
### Trabalhando com Jupyter Notebooks
|
||||
1. Inicie o Jupyter na raiz do repositório: `jupyter notebook`
|
||||
2. Navegue até a pasta da lição desejada
|
||||
3. Abra os ficheiros `.ipynb` para realizar os exercícios
|
||||
4. Os notebooks são autossuficientes, com explicações e células de código
|
||||
5. A maioria dos notebooks utiliza pandas, numpy e matplotlib - certifique-se de que estão instalados
|
||||
|
||||
### Estrutura das Lições
|
||||
Cada lição geralmente contém:
|
||||
- `README.md` - Conteúdo principal da lição com teoria e exemplos
|
||||
- `notebook.ipynb` - Exercícios práticos em Jupyter Notebook
|
||||
- `assignment.ipynb` ou `assignment.md` - Tarefas práticas
|
||||
- Pasta `solution/` - Notebooks e códigos de solução
|
||||
- Pasta `images/` - Materiais visuais de suporte
|
||||
|
||||
### Desenvolvimento da Aplicação de Questionários
|
||||
- Aplicação Vue.js 2 com recarregamento automático durante o desenvolvimento
|
||||
- Questionários armazenados em `quiz-app/src/assets/translations/`
|
||||
- Cada idioma tem a sua própria pasta de tradução (en, fr, es, etc.)
|
||||
- A numeração dos questionários começa em 0 e vai até 39 (40 questionários no total)
|
||||
|
||||
### Adicionando Traduções
|
||||
- Traduções vão para a pasta `translations/` na raiz do repositório
|
||||
- Cada idioma tem uma estrutura completa de lições espelhada do inglês
|
||||
- Tradução automatizada via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instruções de Teste
|
||||
|
||||
### Teste da Aplicação de Questionários
|
||||
```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
|
||||
```
|
||||
|
||||
### Teste de Notebooks
|
||||
- Não existe um framework de teste automatizado para notebooks
|
||||
- Validação manual: Execute todas as células em sequência para garantir que não há erros
|
||||
- Verifique se os ficheiros de dados estão acessíveis e se os resultados são gerados corretamente
|
||||
- Confirme que as visualizações são renderizadas corretamente
|
||||
|
||||
### Teste de Documentação
|
||||
```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
|
||||
```
|
||||
|
||||
### Verificações de Qualidade de Código
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Diretrizes de Estilo de Código
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Siga as diretrizes de estilo PEP 8 para código Python
|
||||
- Use nomes de variáveis claros que expliquem os dados analisados
|
||||
- Inclua células Markdown com explicações antes das células de código
|
||||
- Mantenha as células de código focadas em conceitos ou operações únicas
|
||||
- Use pandas para manipulação de dados, matplotlib para visualização
|
||||
- Padrão comum de importação:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Siga o guia de estilo e as melhores práticas do Vue.js 2
|
||||
- Configuração do ESLint em `quiz-app/package.json`
|
||||
- Use componentes de ficheiro único Vue (.vue files)
|
||||
- Mantenha uma arquitetura baseada em componentes
|
||||
- Execute `npm run lint` antes de submeter alterações
|
||||
|
||||
### Documentação em Markdown
|
||||
- Use uma hierarquia clara de cabeçalhos (# ## ### etc.)
|
||||
- Inclua blocos de código com especificadores de linguagem
|
||||
- Adicione texto alternativo para imagens
|
||||
- Ligue a lições e recursos relacionados
|
||||
- Mantenha comprimentos de linha razoáveis para facilitar a leitura
|
||||
|
||||
### Organização de Ficheiros
|
||||
- Conteúdo das lições em pastas numeradas (01-definindo-ciencia-de-dados, etc.)
|
||||
- Soluções em subpastas dedicadas `solution/`
|
||||
- Traduções espelham a estrutura em inglês na pasta `translations/`
|
||||
- Mantenha os ficheiros de dados na pasta `data/` ou em pastas específicas das lições
|
||||
|
||||
## Construção e Implantação
|
||||
|
||||
### Implantação da Aplicação de Questionários
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Implantação em Azure Static Web Apps
|
||||
A aplicação quiz-app pode ser implantada no Azure Static Web Apps:
|
||||
1. Crie um recurso Azure Static Web App
|
||||
2. Conecte ao repositório GitHub
|
||||
3. Configure as definições de construção:
|
||||
- Localização da aplicação: `quiz-app`
|
||||
- Localização de saída: `dist`
|
||||
4. O fluxo de trabalho do GitHub Actions fará a implantação automática ao fazer push
|
||||
|
||||
### Site de Documentação
|
||||
```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
|
||||
- O repositório inclui configuração de contêiner de desenvolvimento
|
||||
- O Codespaces configura automaticamente o ambiente Python e Node.js
|
||||
- Abra o repositório no Codespace via interface do GitHub
|
||||
- Todas as dependências são instaladas automaticamente
|
||||
|
||||
## Diretrizes para Pull Requests
|
||||
|
||||
### Antes de Submeter
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Formato do Título do PR
|
||||
- Use títulos claros e descritivos
|
||||
- Formato: `[Componente] Breve descrição`
|
||||
- Exemplos:
|
||||
- `[Lição 7] Corrigir erro de importação no notebook Python`
|
||||
- `[Aplicação de Questionários] Adicionar tradução para alemão`
|
||||
- `[Documentação] Atualizar README com novos pré-requisitos`
|
||||
|
||||
### Verificações Necessárias
|
||||
- Certifique-se de que todo o código é executado sem erros
|
||||
- Verifique se os notebooks são executados completamente
|
||||
- Confirme que as aplicações Vue.js são construídas com sucesso
|
||||
- Verifique se os links da documentação funcionam
|
||||
- Teste a aplicação de questionários se modificada
|
||||
- Confirme que as traduções mantêm uma estrutura consistente
|
||||
|
||||
### Diretrizes de Contribuição
|
||||
- Siga o estilo e os padrões de código existentes
|
||||
- Adicione comentários explicativos para lógica complexa
|
||||
- Atualize a documentação relevante
|
||||
- Teste alterações em diferentes módulos de lições, se aplicável
|
||||
- Consulte o ficheiro CONTRIBUTING.md
|
||||
|
||||
## Notas Adicionais
|
||||
|
||||
### Bibliotecas Comuns Utilizadas
|
||||
- **pandas**: Manipulação e análise de dados
|
||||
- **numpy**: Computação numérica
|
||||
- **matplotlib**: Visualização e criação de gráficos
|
||||
- **seaborn**: Visualização estatística de dados (algumas lições)
|
||||
- **scikit-learn**: Aprendizagem de máquina (lições avançadas)
|
||||
|
||||
### Trabalhando com Ficheiros de Dados
|
||||
- Ficheiros de dados localizados na pasta `data/` ou em diretórios específicos das lições
|
||||
- A maioria dos notebooks espera ficheiros de dados em caminhos relativos
|
||||
- Ficheiros CSV são o formato de dados principal
|
||||
- Algumas lições utilizam JSON para exemplos de dados não relacionais
|
||||
|
||||
### Suporte Multilíngue
|
||||
- Mais de 40 traduções de idiomas via GitHub Actions automatizado
|
||||
- Fluxo de trabalho de tradução em `.github/workflows/co-op-translator.yml`
|
||||
- Traduções na pasta `translations/` com códigos de idioma
|
||||
- Traduções de questionários em `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opções de Ambiente de Desenvolvimento
|
||||
1. **Desenvolvimento Local**: Instale Python, Jupyter, Node.js localmente
|
||||
2. **GitHub Codespaces**: Ambiente de desenvolvimento instantâneo na nuvem
|
||||
3. **Contêineres de Desenvolvimento do VS Code**: Desenvolvimento local baseado em contêineres
|
||||
4. **Binder**: Inicie notebooks na nuvem (se configurado)
|
||||
|
||||
### Diretrizes de Conteúdo das Lições
|
||||
- Cada lição é independente, mas constrói conceitos anteriores
|
||||
- Questionários pré-lição testam conhecimentos prévios
|
||||
- Questionários pós-lição reforçam o aprendizado
|
||||
- Tarefas oferecem prática prática
|
||||
- Sketchnotes fornecem resumos visuais
|
||||
|
||||
### Resolução de Problemas Comuns
|
||||
|
||||
**Problemas com o Kernel do Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Falhas na Instalação do npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Erros de Importação em Notebooks:**
|
||||
- Verifique se todas as bibliotecas necessárias estão instaladas
|
||||
- Confirme a compatibilidade da versão do Python (recomenda-se Python 3.7+)
|
||||
- Certifique-se de que o ambiente virtual está ativado
|
||||
|
||||
**Docsify Não Carrega:**
|
||||
- Verifique se está a servir a partir da raiz do repositório
|
||||
- Confirme que o ficheiro `index.html` existe
|
||||
- Certifique-se de que há acesso de rede adequado (porta 3000)
|
||||
|
||||
### Considerações de Desempenho
|
||||
- Conjuntos de dados grandes podem demorar a carregar nos notebooks
|
||||
- A renderização de visualizações pode ser lenta para gráficos complexos
|
||||
- O servidor de desenvolvimento Vue.js permite recarregamento rápido para iteração
|
||||
- As construções de produção são otimizadas e minificadas
|
||||
|
||||
### Notas de Segurança
|
||||
- Não devem ser comprometidos dados sensíveis ou credenciais
|
||||
- Use variáveis de ambiente para quaisquer chaves de API em lições na nuvem
|
||||
- Lições relacionadas ao Azure podem exigir credenciais de conta Azure
|
||||
- Mantenha as dependências atualizadas para correções de segurança
|
||||
|
||||
## Contribuindo com Traduções
|
||||
- Traduções automatizadas geridas via GitHub Actions
|
||||
- Correções manuais são bem-vindas para melhorar a precisão das traduções
|
||||
- Siga a estrutura de pastas de tradução existente
|
||||
- Atualize os links dos questionários para incluir o parâmetro de idioma: `?loc=fr`
|
||||
- Teste as lições traduzidas para garantir a renderização adequada
|
||||
|
||||
## Recursos Relacionados
|
||||
- Currículo principal: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Fórum de Discussão: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Outros currículos da Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Manutenção do Projeto
|
||||
- Atualizações regulares para manter o conteúdo atual
|
||||
- Contribuições da comunidade são bem-vindas
|
||||
- Problemas rastreados no GitHub
|
||||
- PRs revisados pelos mantenedores do currículo
|
||||
- Revisões e atualizações de conteúdo mensais
|
||||
|
||||
---
|
||||
|
||||
**Aviso Legal**:
|
||||
Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se uma tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes do uso desta tradução.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:39:12+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "ro"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Prezentare Generală a Proiectului
|
||||
|
||||
Data Science for Beginners este un curriculum cuprinzător de 10 săptămâni și 20 de lecții, creat de Microsoft Azure Cloud Advocates. Repozitoriul este o resursă educațională care predă concepte fundamentale de știința datelor prin lecții bazate pe proiecte, incluzând notebook-uri Jupyter, chestionare interactive și teme practice.
|
||||
|
||||
**Tehnologii Cheie:**
|
||||
- **Jupyter Notebooks**: Principalul mediu de învățare utilizând Python 3
|
||||
- **Biblioteci Python**: pandas, numpy, matplotlib pentru analiză și vizualizare de date
|
||||
- **Vue.js 2**: Aplicație de chestionare (folderul quiz-app)
|
||||
- **Docsify**: Generator de site-uri de documentație pentru acces offline
|
||||
- **Node.js/npm**: Gestionarea pachetelor pentru componente JavaScript
|
||||
- **Markdown**: Tot conținutul lecțiilor și documentația
|
||||
|
||||
**Arhitectură:**
|
||||
- Repozitoriu educațional multilingv cu traduceri extinse
|
||||
- Structurat în module de lecții (1-Introducere până la 6-Știința-Datelor-În-Lumea-Reală)
|
||||
- Fiecare lecție include README, notebook-uri, teme și chestionare
|
||||
- Aplicație de chestionare Vue.js independentă pentru evaluări pre/post-lecție
|
||||
- Suport pentru GitHub Codespaces și containere de dezvoltare VS Code
|
||||
|
||||
## Comenzi de Configurare
|
||||
|
||||
### Configurarea Repozitoriului
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Configurarea Mediului Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Configurarea Aplicației de Chestionare
|
||||
```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
|
||||
```
|
||||
|
||||
### Serverul de Documentație Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Configurarea Proiectelor de Vizualizare
|
||||
Pentru proiecte de vizualizare precum meaningful-visualizations (lecția 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
|
||||
```
|
||||
|
||||
|
||||
## Flux de Lucru în Dezvoltare
|
||||
|
||||
### Lucrul cu Jupyter Notebooks
|
||||
1. Porniți Jupyter din rădăcina repo-ului: `jupyter notebook`
|
||||
2. Navigați la folderul lecției dorite
|
||||
3. Deschideți fișierele `.ipynb` pentru a lucra la exerciții
|
||||
4. Notebook-urile sunt autonome, cu explicații și celule de cod
|
||||
5. Majoritatea notebook-urilor folosesc pandas, numpy și matplotlib - asigurați-vă că acestea sunt instalate
|
||||
|
||||
### Structura Lecțiilor
|
||||
Fiecare lecție conține, de obicei:
|
||||
- `README.md` - Conținutul principal al lecției cu teorie și exemple
|
||||
- `notebook.ipynb` - Exerciții practice în Jupyter notebook
|
||||
- `assignment.ipynb` sau `assignment.md` - Teme practice
|
||||
- Folderul `solution/` - Notebook-uri și coduri de soluții
|
||||
- Folderul `images/` - Materiale vizuale suport
|
||||
|
||||
### Dezvoltarea Aplicației de Chestionare
|
||||
- Aplicație Vue.js 2 cu reîncărcare automată în timpul dezvoltării
|
||||
- Chestionarele sunt stocate în `quiz-app/src/assets/translations/`
|
||||
- Fiecare limbă are propriul folder de traduceri (en, fr, es etc.)
|
||||
- Numerotarea chestionarelor începe de la 0 și ajunge până la 39 (40 chestionare în total)
|
||||
|
||||
### Adăugarea Traducerilor
|
||||
- Traducerile se află în folderul `translations/` din rădăcina repo-ului
|
||||
- Fiecare limbă are o structură completă a lecțiilor, oglindită din engleză
|
||||
- Traducere automată prin GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Instrucțiuni de Testare
|
||||
|
||||
### Testarea Aplicației de Chestionare
|
||||
```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
|
||||
```
|
||||
|
||||
### Testarea Notebook-urilor
|
||||
- Nu există un cadru de testare automat pentru notebook-uri
|
||||
- Validare manuală: Rulați toate celulele în ordine pentru a vă asigura că nu există erori
|
||||
- Verificați accesibilitatea fișierelor de date și generarea corectă a rezultatelor
|
||||
- Asigurați-vă că vizualizările se redau corect
|
||||
|
||||
### Testarea Documentației
|
||||
```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
|
||||
```
|
||||
|
||||
### Verificări de Calitate a Codului
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Ghiduri de Stil pentru Cod
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Respectați ghidurile de stil PEP 8 pentru codul Python
|
||||
- Folosiți nume de variabile clare care explică datele analizate
|
||||
- Includeți celule markdown cu explicații înainte de celulele de cod
|
||||
- Păstrați celulele de cod concentrate pe concepte sau operațiuni unice
|
||||
- Utilizați pandas pentru manipularea datelor, matplotlib pentru vizualizare
|
||||
- Model comun de import:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Respectați ghidul de stil Vue.js 2 și cele mai bune practici
|
||||
- Configurația ESLint în `quiz-app/package.json`
|
||||
- Utilizați componente Vue single-file (.vue)
|
||||
- Mențineți o arhitectură bazată pe componente
|
||||
- Rulați `npm run lint` înainte de a trimite modificări
|
||||
|
||||
### Documentație Markdown
|
||||
- Utilizați o ierarhie clară a titlurilor (# ## ### etc.)
|
||||
- Includeți blocuri de cod cu specificatori de limbă
|
||||
- Adăugați text alternativ pentru imagini
|
||||
- Link către lecții și resurse conexe
|
||||
- Păstrați lungimea liniilor rezonabilă pentru lizibilitate
|
||||
|
||||
### Organizarea Fișierelor
|
||||
- Conținutul lecțiilor în foldere numerotate (01-defining-data-science etc.)
|
||||
- Soluțiile în subfoldere dedicate `solution/`
|
||||
- Traducerile oglindesc structura engleză în folderul `translations/`
|
||||
- Păstrați fișierele de date în `data/` sau foldere specifice lecțiilor
|
||||
|
||||
## Construire și Implementare
|
||||
|
||||
### Implementarea Aplicației de Chestionare
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Implementarea Azure Static Web Apps
|
||||
Aplicația quiz-app poate fi implementată pe Azure Static Web Apps:
|
||||
1. Creați o resursă Azure Static Web App
|
||||
2. Conectați-vă la repo-ul GitHub
|
||||
3. Configurați setările de construire:
|
||||
- Locația aplicației: `quiz-app`
|
||||
- Locația output-ului: `dist`
|
||||
4. Workflow-ul GitHub Actions va implementa automat la fiecare push
|
||||
|
||||
### Site-ul de Documentație
|
||||
```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
|
||||
- Repozitoriul include configurația containerului de dezvoltare
|
||||
- Codespaces configurează automat mediul Python și Node.js
|
||||
- Deschideți repo-ul în Codespace prin UI-ul GitHub
|
||||
- Toate dependențele se instalează automat
|
||||
|
||||
## Ghiduri pentru Pull Request-uri
|
||||
|
||||
### Înainte de Trimitere
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Formatul Titlului PR
|
||||
- Utilizați titluri clare și descriptive
|
||||
- Format: `[Componentă] Descriere scurtă`
|
||||
- Exemple:
|
||||
- `[Lecția 7] Rezolvă eroarea de import în notebook-ul Python`
|
||||
- `[Aplicația de Chestionare] Adaugă traducerea în germană`
|
||||
- `[Documentație] Actualizează README cu noi cerințe preliminare`
|
||||
|
||||
### Verificări Necesare
|
||||
- Asigurați-vă că tot codul rulează fără erori
|
||||
- Verificați execuția completă a notebook-urilor
|
||||
- Confirmați construirea cu succes a aplicațiilor Vue.js
|
||||
- Verificați funcționarea link-urilor din documentație
|
||||
- Testați aplicația de chestionare dacă a fost modificată
|
||||
- Verificați că traducerile mențin o structură consistentă
|
||||
|
||||
### Ghiduri de Contribuție
|
||||
- Respectați stilul și modelele de cod existente
|
||||
- Adăugați comentarii explicative pentru logica complexă
|
||||
- Actualizați documentația relevantă
|
||||
- Testați modificările în diferite module de lecții, dacă este cazul
|
||||
- Consultați fișierul CONTRIBUTING.md
|
||||
|
||||
## Note Suplimentare
|
||||
|
||||
### Biblioteci Comune Utilizate
|
||||
- **pandas**: Manipularea și analiza datelor
|
||||
- **numpy**: Calcul numeric
|
||||
- **matplotlib**: Vizualizare și graficare de date
|
||||
- **seaborn**: Vizualizare statistică a datelor (unele lecții)
|
||||
- **scikit-learn**: Învățare automată (lecții avansate)
|
||||
|
||||
### Lucrul cu Fișiere de Date
|
||||
- Fișierele de date se află în folderul `data/` sau în directoare specifice lecțiilor
|
||||
- Majoritatea notebook-urilor se așteaptă ca fișierele de date să fie în căi relative
|
||||
- Fișierele CSV sunt formatul principal de date
|
||||
- Unele lecții folosesc JSON pentru exemple de date nerelaționale
|
||||
|
||||
### Suport Multilingv
|
||||
- Peste 40 de traduceri lingvistice prin GitHub Actions automate
|
||||
- Workflow-ul de traducere în `.github/workflows/co-op-translator.yml`
|
||||
- Traducerile în folderul `translations/` cu coduri de limbă
|
||||
- Traducerile chestionarelor în `quiz-app/src/assets/translations/`
|
||||
|
||||
### Opțiuni de Mediu de Dezvoltare
|
||||
1. **Dezvoltare Locală**: Instalați Python, Jupyter, Node.js local
|
||||
2. **GitHub Codespaces**: Mediu de dezvoltare instant în cloud
|
||||
3. **Containere Dev VS Code**: Dezvoltare locală bazată pe containere
|
||||
4. **Binder**: Lansați notebook-uri în cloud (dacă este configurat)
|
||||
|
||||
### Ghiduri pentru Conținutul Lecțiilor
|
||||
- Fiecare lecție este autonomă, dar se bazează pe conceptele anterioare
|
||||
- Chestionarele pre-lecție testează cunoștințele anterioare
|
||||
- Chestionarele post-lecție consolidează învățarea
|
||||
- Temele oferă practică hands-on
|
||||
- Sketchnotes oferă rezumate vizuale
|
||||
|
||||
### Rezolvarea Problemelor Comune
|
||||
|
||||
**Probleme cu Kernel-ul Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Eșecuri la Instalarea npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Erori de Import în Notebook-uri:**
|
||||
- Verificați instalarea tuturor bibliotecilor necesare
|
||||
- Verificați compatibilitatea versiunii Python (recomandat Python 3.7+)
|
||||
- Asigurați-vă că mediul virtual este activat
|
||||
|
||||
**Docsify Nu Se Încarcă:**
|
||||
- Verificați că serviți din rădăcina repo-ului
|
||||
- Asigurați-vă că `index.html` există
|
||||
- Verificați accesul corect la rețea (portul 3000)
|
||||
|
||||
### Considerații de Performanță
|
||||
- Seturile mari de date pot necesita timp pentru încărcare în notebook-uri
|
||||
- Redarea vizualizărilor poate fi lentă pentru grafice complexe
|
||||
- Serverul de dezvoltare Vue.js permite reîncărcare rapidă pentru iterații rapide
|
||||
- Build-urile de producție sunt optimizate și minificate
|
||||
|
||||
### Note de Securitate
|
||||
- Nu trebuie să se comită date sensibile sau credențiale
|
||||
- Utilizați variabile de mediu pentru orice chei API în lecțiile cloud
|
||||
- Lecțiile legate de Azure pot necesita credențiale de cont Azure
|
||||
- Mențineți dependențele actualizate pentru patch-uri de securitate
|
||||
|
||||
## Contribuția la Traduceri
|
||||
- Traducerile automate sunt gestionate prin GitHub Actions
|
||||
- Corecțiile manuale sunt binevenite pentru acuratețea traducerilor
|
||||
- Respectați structura folderului de traduceri existentă
|
||||
- Actualizați link-urile chestionarelor pentru a include parametrul de limbă: `?loc=fr`
|
||||
- Testați lecțiile traduse pentru redarea corectă
|
||||
|
||||
## Resurse Conexe
|
||||
- Curriculum principal: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum de Discuții: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Alte curriculum-uri Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Întreținerea Proiectului
|
||||
- Actualizări regulate pentru a menține conținutul actual
|
||||
- Contribuțiile comunității sunt binevenite
|
||||
- Problemele sunt urmărite pe GitHub
|
||||
- PR-urile sunt revizuite de către mentenorii curriculum-ului
|
||||
- Revizuiri și actualizări lunare ale conținutului
|
||||
|
||||
---
|
||||
|
||||
**Declinare de responsabilitate**:
|
||||
Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim să asigurăm acuratețea, vă rugăm să fiți conștienți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa maternă ar trebui considerat sursa autoritară. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care pot apărea din utilizarea acestei traduceri.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:38:05+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "sk"
|
||||
}
|
||||
-->
|
||||
# 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.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:43:35+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "sl"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Pregled projekta
|
||||
|
||||
Data Science for Beginners je obsežen 10-tedenski, 20-lekcijski učni načrt, ki ga je ustvarila ekipa Microsoft Azure Cloud Advocates. Repozitorij je učni vir, ki poučuje osnovne koncepte podatkovne znanosti skozi lekcije, ki temeljijo na projektih, vključno z Jupyter zvezki, interaktivnimi kvizi in praktičnimi nalogami.
|
||||
|
||||
**Ključne tehnologije:**
|
||||
- **Jupyter zvezki**: Glavno učno sredstvo z uporabo Python 3
|
||||
- **Python knjižnice**: pandas, numpy, matplotlib za analizo podatkov in vizualizacijo
|
||||
- **Vue.js 2**: Aplikacija za kvize (mapa quiz-app)
|
||||
- **Docsify**: Generator dokumentacijskih strani za dostop brez povezave
|
||||
- **Node.js/npm**: Upravljanje paketov za JavaScript komponente
|
||||
- **Markdown**: Vsa vsebina lekcij in dokumentacija
|
||||
|
||||
**Arhitektura:**
|
||||
- Večjezični izobraževalni repozitorij z obsežnimi prevodi
|
||||
- Strukturiran v module lekcij (1-Uvod do 6-Podatkovna znanost v praksi)
|
||||
- Vsaka lekcija vključuje README, zvezke, naloge in kvize
|
||||
- Samostojna aplikacija za kvize Vue.js za ocenjevanje pred/po lekciji
|
||||
- Podpora za GitHub Codespaces in VS Code razvojne vsebnike
|
||||
|
||||
## Ukazi za nastavitev
|
||||
|
||||
### Nastavitev repozitorija
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Nastavitev Python okolja
|
||||
```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
|
||||
```
|
||||
|
||||
### Nastavitev aplikacije za kvize
|
||||
```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 strežnik za dokumentacijo
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Nastavitev projektov za vizualizacijo
|
||||
Za projekte vizualizacije, kot je meaningful-visualizations (lekcija 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
|
||||
```
|
||||
|
||||
|
||||
## Razvojni potek dela
|
||||
|
||||
### Delo z Jupyter zvezki
|
||||
1. Zaženite Jupyter v korenu repozitorija: `jupyter notebook`
|
||||
2. Pomaknite se do želene mape lekcije
|
||||
3. Odprite `.ipynb` datoteke za delo z vajami
|
||||
4. Zvezki so samostojni z razlagami in kodnimi celicami
|
||||
5. Večina zvezkov uporablja pandas, numpy in matplotlib - preverite, da so nameščeni
|
||||
|
||||
### Struktura lekcije
|
||||
Vsaka lekcija običajno vsebuje:
|
||||
- `README.md` - Glavna vsebina lekcije s teorijo in primeri
|
||||
- `notebook.ipynb` - Praktične vaje v Jupyter zvezku
|
||||
- `assignment.ipynb` ali `assignment.md` - Praktične naloge
|
||||
- `solution/` mapa - Zvezki z rešitvami in koda
|
||||
- `images/` mapa - Podporni vizualni materiali
|
||||
|
||||
### Razvoj aplikacije za kvize
|
||||
- Aplikacija Vue.js 2 z možnostjo hitrega osveževanja med razvojem
|
||||
- Kvizi so shranjeni v `quiz-app/src/assets/translations/`
|
||||
- Vsak jezik ima svojo mapo za prevode (en, fr, es itd.)
|
||||
- Številčenje kvizov se začne pri 0 in gre do 39 (skupaj 40 kvizov)
|
||||
|
||||
### Dodajanje prevodov
|
||||
- Prevodi se nahajajo v mapi `translations/` v korenu repozitorija
|
||||
- Vsak jezik ima popolno strukturo lekcij, ki zrcali angleško
|
||||
- Avtomatizirani prevodi prek GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Navodila za testiranje
|
||||
|
||||
### Testiranje aplikacije za kvize
|
||||
```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
|
||||
```
|
||||
|
||||
### Testiranje zvezkov
|
||||
- Za zvezke ne obstaja avtomatiziran testni okvir
|
||||
- Ročna validacija: Zaženite vse celice zaporedoma, da preverite, da ni napak
|
||||
- Preverite dostopnost datotek s podatki in pravilno generiranje izhodov
|
||||
- Preverite, da se vizualizacije pravilno prikažejo
|
||||
|
||||
### Testiranje dokumentacije
|
||||
```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
|
||||
```
|
||||
|
||||
### Preverjanje kakovosti kode
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Smernice za slog kode
|
||||
|
||||
### Python (Jupyter zvezki)
|
||||
- Upoštevajte smernice sloga PEP 8 za Python kodo
|
||||
- Uporabljajte jasna imena spremenljivk, ki pojasnjujejo analizirane podatke
|
||||
- Dodajte markdown celice z razlagami pred kodnimi celicami
|
||||
- Kodne celice naj se osredotočajo na posamezne koncepte ali operacije
|
||||
- Uporabljajte pandas za manipulacijo podatkov, matplotlib za vizualizacijo
|
||||
- Pogost vzorec uvoza:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Upoštevajte smernice sloga Vue.js 2 in najboljše prakse
|
||||
- ESLint konfiguracija v `quiz-app/package.json`
|
||||
- Uporabljajte Vue datoteke z enim komponentom (.vue datoteke)
|
||||
- Ohranjajte arhitekturo, ki temelji na komponentah
|
||||
- Pred oddajo sprememb zaženite `npm run lint`
|
||||
|
||||
### Markdown dokumentacija
|
||||
- Uporabljajte jasno hierarhijo naslovov (# ## ### itd.)
|
||||
- Dodajte kodne bloke z določenimi jeziki
|
||||
- Dodajte alt besedilo za slike
|
||||
- Povezujte na sorodne lekcije in vire
|
||||
- Ohranjajte razumne dolžine vrstic za berljivost
|
||||
|
||||
### Organizacija datotek
|
||||
- Vsebina lekcij v oštevilčenih mapah (01-defining-data-science itd.)
|
||||
- Rešitve v namenskih podmapah `solution/`
|
||||
- Prevodi zrcalijo angleško strukturo v mapi `translations/`
|
||||
- Datoteke s podatki v mapi `data/` ali specifičnih mapah lekcij
|
||||
|
||||
## Gradnja in uvajanje
|
||||
|
||||
### Uvajanje aplikacije za kvize
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Uvajanje Azure Static Web Apps
|
||||
Aplikacijo za kvize lahko uvedete v Azure Static Web Apps:
|
||||
1. Ustvarite vir Azure Static Web App
|
||||
2. Povežite se z GitHub repozitorijem
|
||||
3. Konfigurirajte nastavitve gradnje:
|
||||
- Lokacija aplikacije: `quiz-app`
|
||||
- Lokacija izhoda: `dist`
|
||||
4. GitHub Actions delovni tok bo samodejno uvedel ob potisku
|
||||
|
||||
### Spletno mesto dokumentacije
|
||||
```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
|
||||
- Repozitorij vključuje konfiguracijo razvojnega vsebnika
|
||||
- Codespaces samodejno nastavi Python in Node.js okolje
|
||||
- Odprite repozitorij v Codespace prek GitHub UI
|
||||
- Vse odvisnosti se samodejno namestijo
|
||||
|
||||
## Smernice za zahteve za združitev
|
||||
|
||||
### Pred oddajo
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format naslova PR
|
||||
- Uporabljajte jasne, opisne naslove
|
||||
- Format: `[Komponenta] Kratek opis`
|
||||
- Primeri:
|
||||
- `[Lekcija 7] Popravi napako pri uvozu Python zvezka`
|
||||
- `[Aplikacija za kvize] Dodaj nemški prevod`
|
||||
- `[Dokumentacija] Posodobi README z novimi predpogoji`
|
||||
|
||||
### Zahtevani pregledi
|
||||
- Preverite, da vsa koda deluje brez napak
|
||||
- Preverite, da se zvezki popolnoma izvedejo
|
||||
- Potrdite, da se aplikacije Vue.js uspešno gradijo
|
||||
- Preverite, da povezave v dokumentaciji delujejo
|
||||
- Testirajte aplikacijo za kvize, če je bila spremenjena
|
||||
- Preverite, da prevodi ohranjajo dosledno strukturo
|
||||
|
||||
### Smernice za prispevanje
|
||||
- Upoštevajte obstoječi slog kode in vzorce
|
||||
- Dodajte razlagalne komentarje za kompleksno logiko
|
||||
- Posodobite ustrezno dokumentacijo
|
||||
- Testirajte spremembe v različnih modulih lekcij, če je primerno
|
||||
- Preglejte datoteko CONTRIBUTING.md
|
||||
|
||||
## Dodatne opombe
|
||||
|
||||
### Pogosto uporabljene knjižnice
|
||||
- **pandas**: Manipulacija in analiza podatkov
|
||||
- **numpy**: Numerično računanje
|
||||
- **matplotlib**: Vizualizacija in risanje podatkov
|
||||
- **seaborn**: Statistična vizualizacija podatkov (nekatere lekcije)
|
||||
- **scikit-learn**: Strojno učenje (napredne lekcije)
|
||||
|
||||
### Delo z datotekami s podatki
|
||||
- Datoteke s podatki se nahajajo v mapi `data/` ali specifičnih mapah lekcij
|
||||
- Večina zvezkov pričakuje datoteke s podatki v relativnih poteh
|
||||
- CSV datoteke so primarni format podatkov
|
||||
- Nekatere lekcije uporabljajo JSON za primere nerelacijskih podatkov
|
||||
|
||||
### Večjezična podpora
|
||||
- 40+ jezikovnih prevodov prek avtomatiziranih GitHub Actions
|
||||
- Delovni tok prevodov v `.github/workflows/co-op-translator.yml`
|
||||
- Prevodi v mapi `translations/` z jezikovnimi kodami
|
||||
- Prevodi kvizov v `quiz-app/src/assets/translations/`
|
||||
|
||||
### Možnosti razvojnega okolja
|
||||
1. **Lokalni razvoj**: Namestite Python, Jupyter, Node.js lokalno
|
||||
2. **GitHub Codespaces**: Oblakovno takojšnje razvojno okolje
|
||||
3. **VS Code razvojni vsebniki**: Lokalni razvoj na osnovi vsebnikov
|
||||
4. **Binder**: Zaženite zvezke v oblaku (če je konfigurirano)
|
||||
|
||||
### Smernice za vsebino lekcij
|
||||
- Vsaka lekcija je samostojna, vendar gradi na prejšnjih konceptih
|
||||
- Kvizi pred lekcijo preverjajo predhodno znanje
|
||||
- Kvizi po lekciji krepijo učenje
|
||||
- Naloge omogočajo praktično vadbo
|
||||
- Sketchnotes zagotavljajo vizualne povzetke
|
||||
|
||||
### Reševanje pogostih težav
|
||||
|
||||
**Težave z Jupyter jedrom:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Napake pri namestitvi npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Napake pri uvozu v zvezkih:**
|
||||
- Preverite, da so nameščene vse zahtevane knjižnice
|
||||
- Preverite združljivost različice Python (priporočeno Python 3.7+)
|
||||
- Prepričajte se, da je virtualno okolje aktivirano
|
||||
|
||||
**Docsify se ne nalaga:**
|
||||
- Preverite, da strežnik deluje iz korena repozitorija
|
||||
- Preverite, da obstaja `index.html`
|
||||
- Preverite pravilno omrežno povezavo (port 3000)
|
||||
|
||||
### Premisleki o zmogljivosti
|
||||
- Veliki nabori podatkov lahko trajajo dlje časa za nalaganje v zvezkih
|
||||
- Prikaz vizualizacij je lahko počasen za kompleksne grafe
|
||||
- Vue.js razvojni strežnik omogoča hitro osveževanje za hitro iteracijo
|
||||
- Proizvodne gradnje so optimizirane in minimizirane
|
||||
|
||||
### Opombe o varnosti
|
||||
- Nobeni občutljivi podatki ali poverilnice ne smejo biti vključeni
|
||||
- Uporabljajte okoljske spremenljivke za vse API ključe v lekcijah v oblaku
|
||||
- Lekcije, povezane z Azure, lahko zahtevajo poverilnice za Azure račun
|
||||
- Posodabljajte odvisnosti za varnostne popravke
|
||||
|
||||
## Prispevanje k prevodom
|
||||
- Avtomatizirani prevodi upravljani prek GitHub Actions
|
||||
- Ročne popravke so dobrodošle za natančnost prevodov
|
||||
- Upoštevajte obstoječo strukturo map za prevode
|
||||
- Posodobite povezave kvizov, da vključujejo jezikovni parameter: `?loc=fr`
|
||||
- Testirajte prevedene lekcije za pravilno prikazovanje
|
||||
|
||||
## Sorodni viri
|
||||
- Glavni učni načrt: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Forum za razprave: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Drugi Microsoft učni načrti: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Vzdrževanje projekta
|
||||
- Redne posodobitve za ohranjanje aktualnosti vsebine
|
||||
- Prispevki skupnosti so dobrodošli
|
||||
- Težave se spremljajo na GitHubu
|
||||
- PR-ji pregledani s strani vzdrževalcev učnega načrta
|
||||
- Mesečni pregledi in posodobitve vsebine
|
||||
|
||||
---
|
||||
|
||||
**Omejitev odgovornosti**:
|
||||
Ta dokument je bil preveden z uporabo storitve AI za prevajanje [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem maternem jeziku naj se šteje za avtoritativni vir. Za ključne informacije priporočamo profesionalni človeški prevod. Ne prevzemamo odgovornosti za morebitna nesporazumevanja ali napačne razlage, ki izhajajo iz uporabe tega prevoda.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:24:03+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "sv"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Projektöversikt
|
||||
|
||||
Data Science for Beginners är en omfattande 10-veckors, 20-lektions läroplan skapad av Microsoft Azure Cloud Advocates. Repositoriet är en lärresurs som lär ut grundläggande datavetenskapliga koncept genom projektbaserade lektioner, inklusive Jupyter-notebooks, interaktiva quiz och praktiska uppgifter.
|
||||
|
||||
**Nyckelteknologier:**
|
||||
- **Jupyter Notebooks**: Primärt läromedel med Python 3
|
||||
- **Python-bibliotek**: pandas, numpy, matplotlib för dataanalys och visualisering
|
||||
- **Vue.js 2**: Quiz-applikation (quiz-app-mapp)
|
||||
- **Docsify**: Dokumentationsgenerator för offlineåtkomst
|
||||
- **Node.js/npm**: Paketadministration för JavaScript-komponenter
|
||||
- **Markdown**: Allt lektionsinnehåll och dokumentation
|
||||
|
||||
**Arkitektur:**
|
||||
- Flerspråkigt utbildningsrepository med omfattande översättningar
|
||||
- Strukturerat i lektionsmoduler (1-Introduction till 6-Data-Science-In-Wild)
|
||||
- Varje lektion innehåller README, notebooks, uppgifter och quiz
|
||||
- Fristående Vue.js quiz-applikation för bedömningar före/efter lektion
|
||||
- Stöd för GitHub Codespaces och VS Code utvecklingscontainrar
|
||||
|
||||
## Installationskommandon
|
||||
|
||||
### Repository-installation
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Python-miljöinstallation
|
||||
```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
|
||||
```
|
||||
|
||||
### Quiz-applikationsinstallation
|
||||
```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-dokumentationsserver
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Installation av visualiseringsprojekt
|
||||
För visualiseringsprojekt som meaningful-visualizations (lektion 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
|
||||
```
|
||||
|
||||
|
||||
## Utvecklingsarbetsflöde
|
||||
|
||||
### Arbeta med Jupyter Notebooks
|
||||
1. Starta Jupyter i repositoryns rot: `jupyter notebook`
|
||||
2. Navigera till önskad lektionsmapp
|
||||
3. Öppna `.ipynb`-filer för att arbeta igenom övningar
|
||||
4. Notebooks är självständiga med förklaringar och kodceller
|
||||
5. De flesta notebooks använder pandas, numpy och matplotlib - se till att dessa är installerade
|
||||
|
||||
### Lektionsstruktur
|
||||
Varje lektion innehåller vanligtvis:
|
||||
- `README.md` - Huvudinnehåll med teori och exempel
|
||||
- `notebook.ipynb` - Praktiska Jupyter-notebook-övningar
|
||||
- `assignment.ipynb` eller `assignment.md` - Praktiska uppgifter
|
||||
- `solution/`-mapp - Lösningsnotebooks och kod
|
||||
- `images/`-mapp - Stödjande visuellt material
|
||||
|
||||
### Utveckling av quiz-applikation
|
||||
- Vue.js 2-applikation med hot-reload under utveckling
|
||||
- Quiz lagras i `quiz-app/src/assets/translations/`
|
||||
- Varje språk har sin egen översättningsmapp (en, fr, es, etc.)
|
||||
- Quiznumrering börjar på 0 och går upp till 39 (totalt 40 quiz)
|
||||
|
||||
### Lägga till översättningar
|
||||
- Översättningar placeras i `translations/`-mappen i repositoryns rot
|
||||
- Varje språk har en komplett lektionsstruktur speglad från engelska
|
||||
- Automatiserad översättning via GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Testinstruktioner
|
||||
|
||||
### Testning av quiz-applikation
|
||||
```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
|
||||
```
|
||||
|
||||
### Testning av notebooks
|
||||
- Inget automatiserat testverktyg finns för notebooks
|
||||
- Manuell validering: Kör alla celler i ordning för att säkerställa att inga fel uppstår
|
||||
- Kontrollera att datafiler är åtkomliga och att utdata genereras korrekt
|
||||
- Kontrollera att visualiseringar renderas korrekt
|
||||
|
||||
### Testning av dokumentation
|
||||
```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
|
||||
```
|
||||
|
||||
### Kontroll av kodkvalitet
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Kodstilsguider
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Följ PEP 8-stilguider för Python-kod
|
||||
- Använd tydliga variabelnamn som förklarar den analyserade datan
|
||||
- Inkludera markdown-celler med förklaringar före kodceller
|
||||
- Håll kodceller fokuserade på enskilda koncept eller operationer
|
||||
- Använd pandas för datamanipulation, matplotlib för visualisering
|
||||
- Vanligt importmönster:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Följ Vue.js 2-stilguide och bästa praxis
|
||||
- ESLint-konfiguration i `quiz-app/package.json`
|
||||
- Använd Vue single-file-komponenter (.vue-filer)
|
||||
- Bibehåll komponentbaserad arkitektur
|
||||
- Kör `npm run lint` innan du skickar ändringar
|
||||
|
||||
### Markdown-dokumentation
|
||||
- Använd tydlig rubrikhierarki (# ## ### etc.)
|
||||
- Inkludera kodblock med språkangivelser
|
||||
- Lägg till alt-text för bilder
|
||||
- Länka till relaterade lektioner och resurser
|
||||
- Håll radlängder rimliga för läsbarhet
|
||||
|
||||
### Filorganisation
|
||||
- Lektionsinnehåll i numrerade mappar (01-defining-data-science, etc.)
|
||||
- Lösningar i dedikerade `solution/`-undermappar
|
||||
- Översättningar speglar engelsk struktur i `translations/`-mappen
|
||||
- Håll datafiler i `data/` eller lektionsspecifika mappar
|
||||
|
||||
## Bygg och distribution
|
||||
|
||||
### Distribution av quiz-applikation
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Distribution av Azure Static Web Apps
|
||||
Quiz-applikationen kan distribueras till Azure Static Web Apps:
|
||||
1. Skapa en Azure Static Web App-resurs
|
||||
2. Anslut till GitHub-repository
|
||||
3. Konfigurera bygginställningar:
|
||||
- Applikationsplats: `quiz-app`
|
||||
- Utdata-plats: `dist`
|
||||
4. GitHub Actions-arbetsflöde distribuerar automatiskt vid push
|
||||
|
||||
### Dokumentationssida
|
||||
```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
|
||||
- Repository innehåller utvecklingscontainerkonfiguration
|
||||
- Codespaces ställer automatiskt in Python- och Node.js-miljö
|
||||
- Öppna repository i Codespace via GitHub UI
|
||||
- Alla beroenden installeras automatiskt
|
||||
|
||||
## Riktlinjer för pull requests
|
||||
|
||||
### Innan du skickar in
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format för PR-titlar
|
||||
- Använd tydliga, beskrivande titlar
|
||||
- Format: `[Komponent] Kort beskrivning`
|
||||
- Exempel:
|
||||
- `[Lektion 7] Åtgärda importfel i Python-notebook`
|
||||
- `[Quiz App] Lägg till tysk översättning`
|
||||
- `[Docs] Uppdatera README med nya förutsättningar`
|
||||
|
||||
### Obligatoriska kontroller
|
||||
- Säkerställ att all kod körs utan fel
|
||||
- Verifiera att notebooks exekveras helt
|
||||
- Bekräfta att Vue.js-appar byggs framgångsrikt
|
||||
- Kontrollera att dokumentationslänkar fungerar
|
||||
- Testa quiz-applikationen om den har ändrats
|
||||
- Verifiera att översättningar bibehåller konsekvent struktur
|
||||
|
||||
### Riktlinjer för bidrag
|
||||
- Följ befintlig kodstil och mönster
|
||||
- Lägg till förklarande kommentarer för komplex logik
|
||||
- Uppdatera relevant dokumentation
|
||||
- Testa ändringar över olika lektionsmoduler om tillämpligt
|
||||
- Granska CONTRIBUTING.md-filen
|
||||
|
||||
## Ytterligare anteckningar
|
||||
|
||||
### Vanliga bibliotek som används
|
||||
- **pandas**: Datamanipulation och analys
|
||||
- **numpy**: Numerisk beräkning
|
||||
- **matplotlib**: Datavisualisering och diagram
|
||||
- **seaborn**: Statistisk datavisualisering (vissa lektioner)
|
||||
- **scikit-learn**: Maskininlärning (avancerade lektioner)
|
||||
|
||||
### Arbeta med datafiler
|
||||
- Datafiler finns i `data/`-mappen eller lektionsspecifika kataloger
|
||||
- De flesta notebooks förväntar sig datafiler i relativa sökvägar
|
||||
- CSV-filer är det primära dataformatet
|
||||
- Vissa lektioner använder JSON för exempel på icke-relationell data
|
||||
|
||||
### Flerspråkigt stöd
|
||||
- 40+ språköversättningar via automatiserade GitHub Actions
|
||||
- Översättningsarbetsflöde i `.github/workflows/co-op-translator.yml`
|
||||
- Översättningar i `translations/`-mappen med språkkoder
|
||||
- Quiz-översättningar i `quiz-app/src/assets/translations/`
|
||||
|
||||
### Alternativ för utvecklingsmiljö
|
||||
1. **Lokal utveckling**: Installera Python, Jupyter, Node.js lokalt
|
||||
2. **GitHub Codespaces**: Molnbaserad omedelbar utvecklingsmiljö
|
||||
3. **VS Code Dev Containers**: Lokal containerbaserad utveckling
|
||||
4. **Binder**: Starta notebooks i molnet (om konfigurerat)
|
||||
|
||||
### Riktlinjer för lektionsinnehåll
|
||||
- Varje lektion är fristående men bygger på tidigare koncept
|
||||
- Quiz före lektionen testar förkunskaper
|
||||
- Quiz efter lektionen förstärker lärandet
|
||||
- Uppgifter ger praktisk övning
|
||||
- Sketchnotes ger visuella sammanfattningar
|
||||
|
||||
### Felsökning av vanliga problem
|
||||
|
||||
**Problem med Jupyter-kärnan:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Fel vid npm-installation:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Importfel i notebooks:**
|
||||
- Kontrollera att alla nödvändiga bibliotek är installerade
|
||||
- Kontrollera Python-versionens kompatibilitet (Python 3.7+ rekommenderas)
|
||||
- Säkerställ att den virtuella miljön är aktiverad
|
||||
|
||||
**Docsify laddas inte:**
|
||||
- Kontrollera att du serverar från repositoryns rot
|
||||
- Kontrollera att `index.html` finns
|
||||
- Säkerställ korrekt nätverksåtkomst (port 3000)
|
||||
|
||||
### Prestandahänsyn
|
||||
- Stora dataset kan ta tid att ladda i notebooks
|
||||
- Visualiseringsrendering kan vara långsam för komplexa diagram
|
||||
- Vue.js utvecklingsserver möjliggör hot-reload för snabb iteration
|
||||
- Produktionsbyggen är optimerade och minifierade
|
||||
|
||||
### Säkerhetsanteckningar
|
||||
- Ingen känslig data eller autentiseringsuppgifter bör skickas in
|
||||
- Använd miljövariabler för API-nycklar i molnlektioner
|
||||
- Azure-relaterade lektioner kan kräva Azure-kontouppgifter
|
||||
- Håll beroenden uppdaterade för säkerhetsfixar
|
||||
|
||||
## Bidra till översättningar
|
||||
- Automatiserade översättningar hanteras via GitHub Actions
|
||||
- Manuella korrigeringar välkomnas för översättningsnoggrannhet
|
||||
- Följ befintlig översättningsmappstruktur
|
||||
- Uppdatera quiz-länkar för att inkludera språkparameter: `?loc=fr`
|
||||
- Testa översatta lektioner för korrekt rendering
|
||||
|
||||
## Relaterade resurser
|
||||
- Huvudläroplan: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Diskussionsforum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Andra Microsoft-läroplaner: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Projektunderhåll
|
||||
- Regelbundna uppdateringar för att hålla innehållet aktuellt
|
||||
- Gemenskapsbidrag välkomnas
|
||||
- Problem spåras på GitHub
|
||||
- PRs granskas av läroplansansvariga
|
||||
- Månatliga innehållsgranskningar och uppdateringar
|
||||
|
||||
---
|
||||
|
||||
**Ansvarsfriskrivning**:
|
||||
Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, bör det noteras att automatiserade översättningar kan innehålla fel eller felaktigheter. Det ursprungliga dokumentet på dess originalspråk bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för eventuella missförstånd eller feltolkningar som uppstår vid användning av denna översättning.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:34:03+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "sw"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Muhtasari wa Mradi
|
||||
|
||||
Data Science for Beginners ni mtaala wa kina wa wiki 10, masomo 20 ulioundwa na Microsoft Azure Cloud Advocates. Hifadhi hii ni rasilimali ya kujifunza inayofundisha dhana za msingi za sayansi ya data kupitia masomo yanayotegemea miradi, ikijumuisha Jupyter notebooks, maswali ya maingiliano, na mazoezi ya vitendo.
|
||||
|
||||
**Teknolojia Muhimu:**
|
||||
- **Jupyter Notebooks**: Njia kuu ya kujifunza kwa kutumia Python 3
|
||||
- **Maktaba za Python**: pandas, numpy, matplotlib kwa uchambuzi wa data na uonyeshaji
|
||||
- **Vue.js 2**: Programu ya maswali (folda ya quiz-app)
|
||||
- **Docsify**: Jenereta ya tovuti ya nyaraka kwa ufikiaji wa nje ya mtandao
|
||||
- **Node.js/npm**: Usimamizi wa vifurushi kwa vipengele vya JavaScript
|
||||
- **Markdown**: Yote yaliyomo kwenye masomo na nyaraka
|
||||
|
||||
**Muundo:**
|
||||
- Hifadhi ya elimu ya lugha nyingi yenye tafsiri nyingi
|
||||
- Imeundwa katika moduli za masomo (1-Introduction hadi 6-Data-Science-In-Wild)
|
||||
- Kila somo linajumuisha README, notebooks, mazoezi, na maswali
|
||||
- Programu ya maswali ya Vue.js inayojitegemea kwa tathmini kabla/baada ya somo
|
||||
- Msaada wa GitHub Codespaces na kontena za maendeleo za VS Code
|
||||
|
||||
## Amri za Usanidi
|
||||
|
||||
### Usanidi wa Hifadhi
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Usanidi wa Mazingira ya Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Usanidi wa Programu ya Maswali
|
||||
```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
|
||||
```
|
||||
|
||||
### Seva ya Nyaraka ya Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Usanidi wa Miradi ya Uonyeshaji
|
||||
Kwa miradi ya uonyeshaji kama meaningful-visualizations (somo la 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
|
||||
```
|
||||
|
||||
|
||||
## Mtiririko wa Maendeleo
|
||||
|
||||
### Kufanya Kazi na Jupyter Notebooks
|
||||
1. Anzisha Jupyter katika mzizi wa hifadhi: `jupyter notebook`
|
||||
2. Tembelea folda ya somo unalotaka
|
||||
3. Fungua faili za `.ipynb` ili kufanya mazoezi
|
||||
4. Notebooks ni za kujitegemea zikiwa na maelezo na seli za msimbo
|
||||
5. Notebooks nyingi zinatumia pandas, numpy, na matplotlib - hakikisha zimesakinishwa
|
||||
|
||||
### Muundo wa Somo
|
||||
Kila somo kwa kawaida lina:
|
||||
- `README.md` - Yaliyomo kuu ya somo na nadharia na mifano
|
||||
- `notebook.ipynb` - Mazoezi ya vitendo ya Jupyter notebook
|
||||
- `assignment.ipynb` au `assignment.md` - Mazoezi ya mazoezi
|
||||
- Folda ya `solution/` - Notebooks za suluhisho na msimbo
|
||||
- Folda ya `images/` - Vifaa vya kuonyesha vinavyosaidia
|
||||
|
||||
### Maendeleo ya Programu ya Maswali
|
||||
- Programu ya Vue.js 2 yenye upakiaji wa haraka wakati wa maendeleo
|
||||
- Maswali yamehifadhiwa katika `quiz-app/src/assets/translations/`
|
||||
- Kila lugha ina folda yake ya tafsiri (en, fr, es, nk.)
|
||||
- Nambari ya maswali inaanza 0 na inaendelea hadi 39 (maswali 40 kwa jumla)
|
||||
|
||||
### Kuongeza Tafsiri
|
||||
- Tafsiri zinawekwa katika folda ya `translations/` kwenye mzizi wa hifadhi
|
||||
- Kila lugha ina muundo kamili wa somo unaolingana na Kiingereza
|
||||
- Tafsiri za kiotomatiki kupitia GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Maelekezo ya Kupima
|
||||
|
||||
### Upimaji wa Programu ya Maswali
|
||||
```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
|
||||
```
|
||||
|
||||
### Upimaji wa Notebooks
|
||||
- Hakuna mfumo wa upimaji wa kiotomatiki kwa notebooks
|
||||
- Uthibitishaji wa mwongozo: Endesha seli zote kwa mpangilio ili kuhakikisha hakuna makosa
|
||||
- Hakikisha faili za data zinapatikana na matokeo yanazalishwa kwa usahihi
|
||||
- Angalia kwamba uonyeshaji unachorwa vizuri
|
||||
|
||||
### Upimaji wa Nyaraka
|
||||
```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
|
||||
```
|
||||
|
||||
### Ukaguzi wa Ubora wa Msimbo
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Miongozo ya Mtindo wa Msimbo
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Fuata miongozo ya mtindo wa PEP 8 kwa msimbo wa Python
|
||||
- Tumia majina ya kutofautisha yanayoelezea data inayochambuliwa
|
||||
- Jumuisha seli za markdown zenye maelezo kabla ya seli za msimbo
|
||||
- Weka seli za msimbo zikilenga dhana moja au operesheni moja
|
||||
- Tumia pandas kwa uendeshaji wa data, matplotlib kwa uonyeshaji
|
||||
- Muundo wa kawaida wa uingizaji:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Fuata mwongozo wa mtindo wa Vue.js 2 na mazoea bora
|
||||
- Usanidi wa ESLint katika `quiz-app/package.json`
|
||||
- Tumia vipengele vya faili moja vya Vue (.vue files)
|
||||
- Dumisha muundo wa vipengele
|
||||
- Endesha `npm run lint` kabla ya kuwasilisha mabadiliko
|
||||
|
||||
### Nyaraka za Markdown
|
||||
- Tumia uongozi wa wazi wa vichwa (# ## ### nk.)
|
||||
- Jumuisha vizuizi vya msimbo na viainishi vya lugha
|
||||
- Ongeza maandishi mbadala kwa picha
|
||||
- Unganisha masomo na rasilimali zinazohusiana
|
||||
- Weka urefu wa mistari kuwa wa kusomeka
|
||||
|
||||
### Mpangilio wa Faili
|
||||
- Yaliyomo ya somo katika folda zenye nambari (01-defining-data-science, nk.)
|
||||
- Suluhisho katika folda ndogo ya `solution/`
|
||||
- Tafsiri zinaakisi muundo wa Kiingereza katika folda ya `translations/`
|
||||
- Weka faili za data katika `data/` au folda maalum za somo
|
||||
|
||||
## Ujenzi na Uwekaji
|
||||
|
||||
### Uwekaji wa Programu ya Maswali
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Uwekaji wa Azure Static Web Apps
|
||||
Programu ya quiz-app inaweza kuwekwa kwenye Azure Static Web Apps:
|
||||
1. Unda rasilimali ya Azure Static Web App
|
||||
2. Unganisha na hifadhi ya GitHub
|
||||
3. Sanidi mipangilio ya ujenzi:
|
||||
- Eneo la programu: `quiz-app`
|
||||
- Eneo la matokeo: `dist`
|
||||
4. Mtiririko wa kazi wa GitHub Actions utaweka kiotomatiki unapofanya push
|
||||
|
||||
### Tovuti ya Nyaraka
|
||||
```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
|
||||
- Hifadhi inajumuisha usanidi wa kontena la maendeleo
|
||||
- Codespaces huweka kiotomatiki mazingira ya Python na Node.js
|
||||
- Fungua hifadhi katika Codespace kupitia UI ya GitHub
|
||||
- Vifurushi vyote vinasakinishwa kiotomatiki
|
||||
|
||||
## Miongozo ya Maombi ya Kuvuta (Pull Request)
|
||||
|
||||
### Kabla ya Kuwasilisha
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Muundo wa Kichwa cha PR
|
||||
- Tumia vichwa vya wazi, vya kuelezea
|
||||
- Muundo: `[Sehemu] Maelezo mafupi`
|
||||
- Mifano:
|
||||
- `[Somo la 7] Rekebisha hitilafu ya uingizaji wa notebook ya Python`
|
||||
- `[Programu ya Maswali] Ongeza tafsiri ya Kijerumani`
|
||||
- `[Nyaraka] Sasisha README na mahitaji mapya`
|
||||
|
||||
### Ukaguzi Unaohitajika
|
||||
- Hakikisha msimbo wote unafanya kazi bila makosa
|
||||
- Thibitisha notebooks zinaendeshwa kikamilifu
|
||||
- Hakikisha programu za Vue.js zinajengwa kwa mafanikio
|
||||
- Angalia kwamba viungo vya nyaraka vinafanya kazi
|
||||
- Jaribu programu ya maswali ikiwa imebadilishwa
|
||||
- Thibitisha tafsiri zinadumisha muundo thabiti
|
||||
|
||||
### Miongozo ya Mchango
|
||||
- Fuata mtindo wa msimbo uliopo na mifumo
|
||||
- Ongeza maoni ya kuelezea kwa mantiki ngumu
|
||||
- Sasisha nyaraka husika
|
||||
- Jaribu mabadiliko katika moduli tofauti za somo ikiwa inafaa
|
||||
- Soma faili ya CONTRIBUTING.md
|
||||
|
||||
## Vidokezo vya Ziada
|
||||
|
||||
### Maktaba za Kawaida Zinazotumika
|
||||
- **pandas**: Uendeshaji na uchambuzi wa data
|
||||
- **numpy**: Uhesabu wa namba
|
||||
- **matplotlib**: Uonyeshaji wa data na uchoraji
|
||||
- **seaborn**: Uonyeshaji wa data wa takwimu (masomo fulani)
|
||||
- **scikit-learn**: Kujifunza kwa mashine (masomo ya juu)
|
||||
|
||||
### Kufanya Kazi na Faili za Data
|
||||
- Faili za data ziko katika folda ya `data/` au folda maalum za somo
|
||||
- Notebooks nyingi zinatarajia faili za data katika njia za jamaa
|
||||
- Faili za CSV ni muundo wa msingi wa data
|
||||
- Masomo fulani yanatumia JSON kwa mifano ya data isiyo ya uhusiano
|
||||
|
||||
### Msaada wa Lugha Nyingi
|
||||
- Tafsiri 40+ za lugha kupitia GitHub Actions za kiotomatiki
|
||||
- Mtiririko wa tafsiri katika `.github/workflows/co-op-translator.yml`
|
||||
- Tafsiri katika folda ya `translations/` yenye misimbo ya lugha
|
||||
- Tafsiri za maswali katika `quiz-app/src/assets/translations/`
|
||||
|
||||
### Chaguo za Mazingira ya Maendeleo
|
||||
1. **Maendeleo ya Ndani**: Sakinisha Python, Jupyter, Node.js ndani
|
||||
2. **GitHub Codespaces**: Mazingira ya maendeleo ya papo hapo ya wingu
|
||||
3. **VS Code Dev Containers**: Maendeleo ya ndani kwa kutumia kontena
|
||||
4. **Binder**: Fungua notebooks katika wingu (ikiwa imewekwa)
|
||||
|
||||
### Miongozo ya Yaliyomo ya Somo
|
||||
- Kila somo ni la kujitegemea lakini linajenga dhana za awali
|
||||
- Maswali ya kabla ya somo yanapima maarifa ya awali
|
||||
- Maswali ya baada ya somo yanasisitiza kujifunza
|
||||
- Mazoezi yanatoa mazoezi ya vitendo
|
||||
- Sketchnotes zinatoa muhtasari wa kuona
|
||||
|
||||
### Kutatua Masuala ya Kawaida
|
||||
|
||||
**Masuala ya Kernel ya Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Hitilafu za Usakinishaji wa npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Hitilafu za Uingizaji katika Notebooks:**
|
||||
- Thibitisha maktaba zote zinazohitajika zimesakinishwa
|
||||
- Angalia utangamano wa toleo la Python (Python 3.7+ inapendekezwa)
|
||||
- Hakikisha mazingira ya kawaida yamewezeshwa
|
||||
|
||||
**Docsify Haipakii:**
|
||||
- Thibitisha unahudumia kutoka mzizi wa hifadhi
|
||||
- Angalia kwamba `index.html` ipo
|
||||
- Hakikisha ufikiaji sahihi wa mtandao (bandari 3000)
|
||||
|
||||
### Mazingatio ya Utendaji
|
||||
- Seti kubwa za data zinaweza kuchukua muda kupakia katika notebooks
|
||||
- Uchoraji wa uonyeshaji unaweza kuwa polepole kwa michoro ngumu
|
||||
- Seva ya maendeleo ya Vue.js inawezesha upakiaji wa haraka kwa kurudia haraka
|
||||
- Ujenzi wa uzalishaji umeboreshwa na umepunguzwa
|
||||
|
||||
### Vidokezo vya Usalama
|
||||
- Hakuna data nyeti au hati za siri zinapaswa kuwasilishwa
|
||||
- Tumia vigezo vya mazingira kwa funguo zozote za API katika masomo ya wingu
|
||||
- Masomo yanayohusiana na Azure yanaweza kuhitaji hati za akaunti ya Azure
|
||||
- Weka maktaba zikiwa zimesasishwa kwa viraka vya usalama
|
||||
|
||||
## Kuchangia Tafsiri
|
||||
- Tafsiri za kiotomatiki zinasimamiwa kupitia GitHub Actions
|
||||
- Marekebisho ya mwongozo yanakaribishwa kwa usahihi wa tafsiri
|
||||
- Fuata muundo wa folda ya tafsiri uliopo
|
||||
- Sasisha viungo vya maswali ili kujumuisha parameter ya lugha: `?loc=fr`
|
||||
- Jaribu masomo yaliyotafsiriwa ili kuhakikisha yanachapishwa vizuri
|
||||
|
||||
## Rasilimali Zinazohusiana
|
||||
- Mtaala kuu: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Jukwaa la Majadiliano: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Mitaala mingine ya Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Matengenezo ya Mradi
|
||||
- Sasisho za mara kwa mara ili kuweka yaliyomo kuwa ya sasa
|
||||
- Michango ya jamii inakaribishwa
|
||||
- Masuala yanafuatiliwa kwenye GitHub
|
||||
- PRs zinakaguliwa na waangalizi wa mtaala
|
||||
- Mapitio na sasisho za yaliyomo kila mwezi
|
||||
|
||||
---
|
||||
|
||||
**Kanusho**:
|
||||
Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kuhakikisha usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au kutokuwa sahihi. Hati ya asili katika lugha yake ya awali inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatutawajibika kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii.
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:22:55+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "th"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## ภาพรวมของโครงการ
|
||||
|
||||
Data Science for Beginners เป็นหลักสูตรที่ครอบคลุมระยะเวลา 10 สัปดาห์ รวม 20 บทเรียน ซึ่งสร้างขึ้นโดย Microsoft Azure Cloud Advocates โดยที่เก็บนี้เป็นแหล่งเรียนรู้ที่สอนแนวคิดพื้นฐานของวิทยาศาสตร์ข้อมูลผ่านบทเรียนที่เน้นโครงการ รวมถึง Jupyter notebooks, แบบทดสอบเชิงโต้ตอบ และการมอบหมายงานที่ต้องลงมือปฏิบัติ
|
||||
|
||||
**เทคโนโลยีหลัก:**
|
||||
- **Jupyter Notebooks**: สื่อการเรียนรู้หลักที่ใช้ Python 3
|
||||
- **Python Libraries**: pandas, numpy, matplotlib สำหรับการวิเคราะห์และการแสดงผลข้อมูล
|
||||
- **Vue.js 2**: แอปพลิเคชันแบบทดสอบ (โฟลเดอร์ quiz-app)
|
||||
- **Docsify**: ตัวสร้างเว็บไซต์เอกสารสำหรับการเข้าถึงแบบออฟไลน์
|
||||
- **Node.js/npm**: การจัดการแพ็กเกจสำหรับส่วนประกอบ JavaScript
|
||||
- **Markdown**: เนื้อหาบทเรียนและเอกสารทั้งหมด
|
||||
|
||||
**สถาปัตยกรรม:**
|
||||
- ที่เก็บการศึกษาหลายภาษา พร้อมการแปลที่ครอบคลุม
|
||||
- โครงสร้างแบ่งเป็นโมดูลบทเรียน (1-Introduction ถึง 6-Data-Science-In-Wild)
|
||||
- แต่ละบทเรียนประกอบด้วย README, notebooks, การมอบหมายงาน และแบบทดสอบ
|
||||
- แอปพลิเคชันแบบทดสอบ Vue.js แบบสแตนด์อโลนสำหรับการประเมินก่อน/หลังบทเรียน
|
||||
- รองรับ GitHub Codespaces และ VS Code dev containers
|
||||
|
||||
## คำสั่งการตั้งค่า
|
||||
|
||||
### การตั้งค่าที่เก็บ
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### การตั้งค่าสภาพแวดล้อม Python
|
||||
```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
|
||||
```
|
||||
|
||||
### การตั้งค่าแอปพลิเคชันแบบทดสอบ
|
||||
```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
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### การตั้งค่าโครงการการแสดงผล
|
||||
สำหรับโครงการการแสดงผล เช่น meaningful-visualizations (บทเรียนที่ 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
|
||||
```
|
||||
|
||||
|
||||
## เวิร์กโฟลว์การพัฒนา
|
||||
|
||||
### การทำงานกับ Jupyter Notebooks
|
||||
1. เริ่มต้น Jupyter ในโฟลเดอร์รากของที่เก็บ: `jupyter notebook`
|
||||
2. ไปยังโฟลเดอร์บทเรียนที่ต้องการ
|
||||
3. เปิดไฟล์ `.ipynb` เพื่อทำแบบฝึกหัด
|
||||
4. Notebooks มีคำอธิบายและเซลล์โค้ดในตัว
|
||||
5. ส่วนใหญ่ใช้ pandas, numpy และ matplotlib - ตรวจสอบให้แน่ใจว่าติดตั้งแล้ว
|
||||
|
||||
### โครงสร้างบทเรียน
|
||||
แต่ละบทเรียนมักประกอบด้วย:
|
||||
- `README.md` - เนื้อหาหลักของบทเรียนพร้อมทฤษฎีและตัวอย่าง
|
||||
- `notebook.ipynb` - แบบฝึกหัด Jupyter notebook
|
||||
- `assignment.ipynb` หรือ `assignment.md` - การมอบหมายงานเพื่อฝึกฝน
|
||||
- โฟลเดอร์ `solution/` - โน้ตบุ๊กและโค้ดคำตอบ
|
||||
- โฟลเดอร์ `images/` - วัสดุภาพประกอบ
|
||||
|
||||
### การพัฒนาแอปพลิเคชันแบบทดสอบ
|
||||
- แอปพลิเคชัน Vue.js 2 พร้อม hot-reload ระหว่างการพัฒนา
|
||||
- แบบทดสอบจัดเก็บใน `quiz-app/src/assets/translations/`
|
||||
- แต่ละภาษามีโฟลเดอร์การแปลของตัวเอง (en, fr, es, ฯลฯ)
|
||||
- หมายเลขแบบทดสอบเริ่มต้นที่ 0 และไปจนถึง 39 (รวม 40 แบบทดสอบ)
|
||||
|
||||
### การเพิ่มการแปลภาษา
|
||||
- การแปลอยู่ในโฟลเดอร์ `translations/` ที่รากของที่เก็บ
|
||||
- แต่ละภาษามีโครงสร้างบทเรียนที่สมบูรณ์เหมือนภาษาอังกฤษ
|
||||
- การแปลอัตโนมัติผ่าน GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## คำแนะนำการทดสอบ
|
||||
|
||||
### การทดสอบแอปพลิเคชันแบบทดสอบ
|
||||
```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
|
||||
```
|
||||
|
||||
### การทดสอบโน้ตบุ๊ก
|
||||
- ไม่มีกรอบการทดสอบอัตโนมัติสำหรับโน้ตบุ๊ก
|
||||
- การตรวจสอบด้วยตนเอง: รันเซลล์ทั้งหมดตามลำดับเพื่อให้แน่ใจว่าไม่มีข้อผิดพลาด
|
||||
- ตรวจสอบว่าไฟล์ข้อมูลสามารถเข้าถึงได้และผลลัพธ์ถูกสร้างขึ้นอย่างถูกต้อง
|
||||
- ตรวจสอบว่าการแสดงผลภาพทำงานได้อย่างเหมาะสม
|
||||
|
||||
### การทดสอบเอกสาร
|
||||
```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
|
||||
```
|
||||
|
||||
### การตรวจสอบคุณภาพโค้ด
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## แนวทางการเขียนโค้ด
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- ปฏิบัติตามแนวทางสไตล์ PEP 8 สำหรับโค้ด Python
|
||||
- ใช้ชื่อตัวแปรที่ชัดเจนซึ่งอธิบายข้อมูลที่กำลังวิเคราะห์
|
||||
- รวมเซลล์ markdown พร้อมคำอธิบายก่อนเซลล์โค้ด
|
||||
- ให้เซลล์โค้ดมุ่งเน้นไปที่แนวคิดหรือการดำเนินการเดียว
|
||||
- ใช้ pandas สำหรับการจัดการข้อมูล, matplotlib สำหรับการแสดงผล
|
||||
- รูปแบบการนำเข้าทั่วไป:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- ปฏิบัติตามแนวทางสไตล์ Vue.js 2 และแนวปฏิบัติที่ดีที่สุด
|
||||
- การกำหนดค่า ESLint ใน `quiz-app/package.json`
|
||||
- ใช้ส่วนประกอบ Vue แบบไฟล์เดียว (.vue files)
|
||||
- รักษาสถาปัตยกรรมที่เน้นส่วนประกอบ
|
||||
- รัน `npm run lint` ก่อนการ commit การเปลี่ยนแปลง
|
||||
|
||||
### เอกสาร Markdown
|
||||
- ใช้ลำดับชั้นหัวข้อที่ชัดเจน (# ## ### ฯลฯ)
|
||||
- รวมบล็อกโค้ดพร้อมตัวระบุภาษา
|
||||
- เพิ่มข้อความ alt สำหรับภาพ
|
||||
- ลิงก์ไปยังบทเรียนและแหล่งข้อมูลที่เกี่ยวข้อง
|
||||
- รักษาความยาวบรรทัดให้อ่านง่าย
|
||||
|
||||
### การจัดระเบียบไฟล์
|
||||
- เนื้อหาบทเรียนในโฟลเดอร์ที่มีหมายเลข (01-defining-data-science ฯลฯ)
|
||||
- คำตอบในโฟลเดอร์ย่อย `solution/` โดยเฉพาะ
|
||||
- การแปลโครงสร้างเหมือนภาษาอังกฤษในโฟลเดอร์ `translations/`
|
||||
- เก็บไฟล์ข้อมูลใน `data/` หรือโฟลเดอร์เฉพาะบทเรียน
|
||||
|
||||
## การสร้างและการปรับใช้
|
||||
|
||||
### การปรับใช้แอปพลิเคชันแบบทดสอบ
|
||||
```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.)
|
||||
```
|
||||
|
||||
### การปรับใช้ Azure Static Web Apps
|
||||
แอป quiz-app สามารถปรับใช้กับ Azure Static Web Apps:
|
||||
1. สร้างทรัพยากร Azure Static Web App
|
||||
2. เชื่อมต่อกับที่เก็บ GitHub
|
||||
3. กำหนดค่าการตั้งค่าการสร้าง:
|
||||
- ตำแหน่งแอป: `quiz-app`
|
||||
- ตำแหน่งผลลัพธ์: `dist`
|
||||
4. GitHub Actions workflow จะปรับใช้อัตโนมัติเมื่อมีการ push
|
||||
|
||||
### เว็บไซต์เอกสาร
|
||||
```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
|
||||
- ที่เก็บรวมการกำหนดค่า dev container
|
||||
- Codespaces ตั้งค่าสภาพแวดล้อม Python และ Node.js โดยอัตโนมัติ
|
||||
- เปิดที่เก็บใน Codespace ผ่าน UI ของ GitHub
|
||||
- การติดตั้งการพึ่งพาทั้งหมดจะดำเนินการโดยอัตโนมัติ
|
||||
|
||||
## แนวทางการส่ง Pull Request
|
||||
|
||||
### ก่อนการส่ง
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### รูปแบบชื่อ PR
|
||||
- ใช้ชื่อที่ชัดเจนและอธิบายได้
|
||||
- รูปแบบ: `[Component] คำอธิบายสั้นๆ`
|
||||
- ตัวอย่าง:
|
||||
- `[Lesson 7] แก้ไขข้อผิดพลาดการนำเข้า Python notebook`
|
||||
- `[Quiz App] เพิ่มการแปลภาษาเยอรมัน`
|
||||
- `[Docs] อัปเดต README พร้อมข้อกำหนดเบื้องต้นใหม่`
|
||||
|
||||
### การตรวจสอบที่จำเป็น
|
||||
- ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมดทำงานได้โดยไม่มีข้อผิดพลาด
|
||||
- ยืนยันว่าโน้ตบุ๊กทำงานได้สมบูรณ์
|
||||
- ยืนยันว่าแอป Vue.js สร้างสำเร็จ
|
||||
- ตรวจสอบว่าเอกสารลิงก์ทำงานได้
|
||||
- ทดสอบแอปพลิเคชันแบบทดสอบหากมีการแก้ไข
|
||||
- ยืนยันว่าโครงสร้างการแปลยังคงสอดคล้องกัน
|
||||
|
||||
### แนวทางการมีส่วนร่วม
|
||||
- ปฏิบัติตามสไตล์และรูปแบบโค้ดที่มีอยู่
|
||||
- เพิ่มความคิดเห็นอธิบายสำหรับตรรกะที่ซับซ้อน
|
||||
- อัปเดตเอกสารที่เกี่ยวข้อง
|
||||
- ทดสอบการเปลี่ยนแปลงในโมดูลบทเรียนต่างๆ หากเกี่ยวข้อง
|
||||
- อ่านไฟล์ CONTRIBUTING.md
|
||||
|
||||
## หมายเหตุเพิ่มเติม
|
||||
|
||||
### ไลบรารีที่ใช้บ่อย
|
||||
- **pandas**: การจัดการและวิเคราะห์ข้อมูล
|
||||
- **numpy**: การคำนวณเชิงตัวเลข
|
||||
- **matplotlib**: การแสดงผลและการพล็อตข้อมูล
|
||||
- **seaborn**: การแสดงผลข้อมูลเชิงสถิติ (บางบทเรียน)
|
||||
- **scikit-learn**: การเรียนรู้ของเครื่อง (บทเรียนขั้นสูง)
|
||||
|
||||
### การทำงานกับไฟล์ข้อมูล
|
||||
- ไฟล์ข้อมูลอยู่ในโฟลเดอร์ `data/` หรือไดเรกทอรีเฉพาะบทเรียน
|
||||
- โน้ตบุ๊กส่วนใหญ่คาดหวังไฟล์ข้อมูลในเส้นทางสัมพัทธ์
|
||||
- ไฟล์ CSV เป็นรูปแบบข้อมูลหลัก
|
||||
- บางบทเรียนใช้ JSON สำหรับตัวอย่างข้อมูลที่ไม่ใช่เชิงสัมพันธ์
|
||||
|
||||
### การสนับสนุนหลายภาษา
|
||||
- การแปลมากกว่า 40 ภาษา ผ่าน GitHub Actions อัตโนมัติ
|
||||
- เวิร์กโฟลว์การแปลใน `.github/workflows/co-op-translator.yml`
|
||||
- การแปลในโฟลเดอร์ `translations/` พร้อมรหัสภาษา
|
||||
- การแปลแบบทดสอบใน `quiz-app/src/assets/translations/`
|
||||
|
||||
### ตัวเลือกสภาพแวดล้อมการพัฒนา
|
||||
1. **การพัฒนาในเครื่อง**: ติดตั้ง Python, Jupyter, Node.js ในเครื่อง
|
||||
2. **GitHub Codespaces**: สภาพแวดล้อมการพัฒนาแบบคลาวด์ทันที
|
||||
3. **VS Code Dev Containers**: การพัฒนาบนคอนเทนเนอร์ในเครื่อง
|
||||
4. **Binder**: เปิดโน้ตบุ๊กในคลาวด์ (หากกำหนดค่าไว้)
|
||||
|
||||
### แนวทางเนื้อหาบทเรียน
|
||||
- แต่ละบทเรียนเป็นแบบสแตนด์อโลนแต่สร้างขึ้นจากแนวคิดก่อนหน้า
|
||||
- แบบทดสอบก่อนบทเรียนทดสอบความรู้ก่อนหน้า
|
||||
- แบบทดสอบหลังบทเรียนเสริมสร้างการเรียนรู้
|
||||
- การมอบหมายงานให้โอกาสฝึกฝน
|
||||
- Sketchnotes ให้สรุปภาพรวม
|
||||
|
||||
### การแก้ไขปัญหาทั่วไป
|
||||
|
||||
**ปัญหา Jupyter Kernel:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**ข้อผิดพลาด npm Install:**
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
### ข้อควรพิจารณาด้านประสิทธิภาพ
|
||||
- ชุดข้อมูลขนาดใหญ่อาจใช้เวลาโหลดในโน้ตบุ๊ก
|
||||
- การแสดงผลภาพอาจช้าสำหรับพล็อตที่ซับซ้อน
|
||||
- เซิร์ฟเวอร์ dev ของ Vue.js เปิดใช้งาน hot-reload สำหรับการทำซ้ำอย่างรวดเร็ว
|
||||
- การสร้างสำหรับการใช้งานจริงได้รับการปรับให้เหมาะสมและย่อขนาด
|
||||
|
||||
### หมายเหตุด้านความปลอดภัย
|
||||
- ห้าม commit ข้อมูลหรือข้อมูลประจำตัวที่ละเอียดอ่อน
|
||||
- ใช้ตัวแปรสภาพแวดล้อมสำหรับคีย์ API ในบทเรียนคลาวด์
|
||||
- บทเรียนที่เกี่ยวข้องกับ Azure อาจต้องใช้ข้อมูลประจำตัวบัญชี Azure
|
||||
- อัปเดตการพึ่งพาเพื่อรับแพตช์ความปลอดภัย
|
||||
|
||||
## การมีส่วนร่วมในการแปล
|
||||
- การแปลอัตโนมัติจัดการผ่าน GitHub Actions
|
||||
- ยินดีต้อนรับการแก้ไขด้วยตนเองเพื่อความถูกต้องของการแปล
|
||||
- ปฏิบัติตามโครงสร้างโฟลเดอร์การแปลที่มีอยู่
|
||||
- อัปเดตลิงก์แบบทดสอบให้รวมพารามิเตอร์ภาษา: `?loc=fr`
|
||||
- ทดสอบบทเรียนที่แปลเพื่อให้แน่ใจว่าการแสดงผลถูกต้อง
|
||||
|
||||
## แหล่งข้อมูลที่เกี่ยวข้อง
|
||||
- หลักสูตรหลัก: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: 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
|
||||
- PRs ตรวจสอบโดยผู้ดูแลหลักสูตร
|
||||
- การตรวจสอบและอัปเดตเนื้อหารายเดือน
|
||||
|
||||
---
|
||||
|
||||
**ข้อจำกัดความรับผิดชอบ**:
|
||||
เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้ว่าเราจะพยายามให้การแปลมีความถูกต้องมากที่สุด แต่โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาดั้งเดิมควรถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้บริการแปลภาษามนุษย์ที่มีความเชี่ยวชาญ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดที่เกิดจากการใช้การแปลนี้
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:32:55+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "tl"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Pangkalahatang-ideya ng Proyekto
|
||||
|
||||
Ang Data Science for Beginners ay isang komprehensibong kurikulum na tumatagal ng 10 linggo at may 20 aralin, na ginawa ng Microsoft Azure Cloud Advocates. Ang repositoryo ay isang mapagkukunan ng pag-aaral na nagtuturo ng mga pangunahing konsepto ng data science sa pamamagitan ng mga aralin na nakabatay sa proyekto, kabilang ang mga Jupyter notebook, interactive na pagsusulit, at mga praktikal na gawain.
|
||||
|
||||
**Pangunahing Teknolohiya:**
|
||||
- **Jupyter Notebooks**: Pangunahing medium ng pag-aaral gamit ang Python 3
|
||||
- **Python Libraries**: pandas, numpy, matplotlib para sa pagsusuri at visualisasyon ng data
|
||||
- **Vue.js 2**: Aplikasyon ng pagsusulit (quiz-app folder)
|
||||
- **Docsify**: Tagabuo ng site ng dokumentasyon para sa offline na access
|
||||
- **Node.js/npm**: Pamamahala ng package para sa mga JavaScript na bahagi
|
||||
- **Markdown**: Lahat ng nilalaman ng aralin at dokumentasyon
|
||||
|
||||
**Arkitektura:**
|
||||
- Repositoryo na pang-edukasyon na multi-wika na may malawak na mga pagsasalin
|
||||
- Nakabalangkas sa mga module ng aralin (1-Introduction hanggang 6-Data-Science-In-Wild)
|
||||
- Ang bawat aralin ay may kasamang README, mga notebook, mga gawain, at mga pagsusulit
|
||||
- Standalone Vue.js na aplikasyon ng pagsusulit para sa pre/post-lesson assessments
|
||||
- Suporta para sa GitHub Codespaces at VS Code dev containers
|
||||
|
||||
## Mga Utos sa Setup
|
||||
|
||||
### Setup ng Repositoryo
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Setup ng Python Environment
|
||||
```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
|
||||
```
|
||||
|
||||
### Setup ng Aplikasyon ng Pagsusulit
|
||||
```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 Documentation Server
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Setup ng Mga Proyekto ng Visualisasyon
|
||||
Para sa mga proyekto ng visualisasyon tulad ng meaningful-visualizations (lesson 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
|
||||
```
|
||||
|
||||
|
||||
## Workflow ng Pag-develop
|
||||
|
||||
### Paggamit ng Jupyter Notebooks
|
||||
1. Simulan ang Jupyter sa root ng repositoryo: `jupyter notebook`
|
||||
2. Mag-navigate sa nais na folder ng aralin
|
||||
3. Buksan ang mga `.ipynb` file upang magtrabaho sa mga ehersisyo
|
||||
4. Ang mga notebook ay self-contained na may mga paliwanag at code cells
|
||||
5. Karamihan sa mga notebook ay gumagamit ng pandas, numpy, at matplotlib - tiyaking naka-install ang mga ito
|
||||
|
||||
### Estruktura ng Aralin
|
||||
Ang bawat aralin ay karaniwang naglalaman ng:
|
||||
- `README.md` - Pangunahing nilalaman ng aralin na may teorya at mga halimbawa
|
||||
- `notebook.ipynb` - Mga praktikal na ehersisyo sa Jupyter notebook
|
||||
- `assignment.ipynb` o `assignment.md` - Mga gawain para sa pagsasanay
|
||||
- `solution/` folder - Mga notebook ng solusyon at code
|
||||
- `images/` folder - Mga sumusuportang visual na materyales
|
||||
|
||||
### Pag-develop ng Aplikasyon ng Pagsusulit
|
||||
- Aplikasyon ng Vue.js 2 na may hot-reload sa panahon ng pag-develop
|
||||
- Ang mga pagsusulit ay naka-imbak sa `quiz-app/src/assets/translations/`
|
||||
- Ang bawat wika ay may sariling folder ng pagsasalin (en, fr, es, atbp.)
|
||||
- Ang pagbilang ng pagsusulit ay nagsisimula sa 0 at umaabot hanggang 39 (40 pagsusulit sa kabuuan)
|
||||
|
||||
### Pagdaragdag ng Mga Pagsasalin
|
||||
- Ang mga pagsasalin ay inilalagay sa `translations/` folder sa root ng repositoryo
|
||||
- Ang bawat wika ay may kumpletong estruktura ng aralin na ginaya mula sa Ingles
|
||||
- Automated na pagsasalin sa pamamagitan ng GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Mga Tagubilin sa Pagsubok
|
||||
|
||||
### Pagsubok ng Aplikasyon ng Pagsusulit
|
||||
```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
|
||||
```
|
||||
|
||||
### Pagsubok ng Notebook
|
||||
- Walang automated na test framework para sa mga notebook
|
||||
- Manu-manong pag-validate: Patakbuhin ang lahat ng cells nang sunod-sunod upang tiyakin na walang error
|
||||
- Siguraduhing naa-access ang mga data file at tama ang mga output
|
||||
- Tiyakin na maayos ang pag-render ng mga visualisasyon
|
||||
|
||||
### Pagsubok ng Dokumentasyon
|
||||
```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
|
||||
```
|
||||
|
||||
### Mga Pag-check ng Kalidad ng Code
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Mga Alituntunin sa Estilo ng Code
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Sundin ang PEP 8 na mga alituntunin sa estilo para sa Python code
|
||||
- Gumamit ng malinaw na pangalan ng variable na nagpapaliwanag sa data na sinusuri
|
||||
- Maglagay ng markdown cells na may mga paliwanag bago ang mga code cells
|
||||
- Panatilihing nakatuon ang mga code cells sa iisang konsepto o operasyon
|
||||
- Gumamit ng pandas para sa manipulasyon ng data, matplotlib para sa visualisasyon
|
||||
- Karaniwang pattern ng import:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Sundin ang Vue.js 2 na gabay sa estilo at pinakamahusay na mga kasanayan
|
||||
- ESLint configuration sa `quiz-app/package.json`
|
||||
- Gumamit ng Vue single-file components (.vue files)
|
||||
- Panatilihin ang arkitektura na nakabatay sa mga bahagi
|
||||
- Patakbuhin ang `npm run lint` bago mag-commit ng mga pagbabago
|
||||
|
||||
### Markdown Documentation
|
||||
- Gumamit ng malinaw na hierarchy ng mga heading (# ## ### atbp.)
|
||||
- Maglagay ng mga code block na may mga specifier ng wika
|
||||
- Magdagdag ng alt text para sa mga imahe
|
||||
- Mag-link sa mga kaugnay na aralin at mapagkukunan
|
||||
- Panatilihing maayos ang haba ng linya para sa readability
|
||||
|
||||
### Organisasyon ng File
|
||||
- Nilalaman ng aralin sa mga folder na may numero (01-defining-data-science, atbp.)
|
||||
- Mga solusyon sa dedikadong `solution/` subfolders
|
||||
- Ang mga pagsasalin ay ginagaya ang estruktura ng Ingles sa `translations/` folder
|
||||
- Panatilihin ang mga data file sa `data/` o mga folder na partikular sa aralin
|
||||
|
||||
## Build at Deployment
|
||||
|
||||
### Deployment ng Aplikasyon ng Pagsusulit
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Deployment ng Azure Static Web Apps
|
||||
Ang quiz-app ay maaaring i-deploy sa Azure Static Web Apps:
|
||||
1. Gumawa ng Azure Static Web App resource
|
||||
2. Ikonekta sa GitHub repository
|
||||
3. I-configure ang mga setting ng build:
|
||||
- Lokasyon ng app: `quiz-app`
|
||||
- Lokasyon ng output: `dist`
|
||||
4. Ang workflow ng GitHub Actions ay awtomatikong mag-deploy kapag may push
|
||||
|
||||
### Site ng Dokumentasyon
|
||||
```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
|
||||
- Ang repositoryo ay may kasamang dev container configuration
|
||||
- Ang Codespaces ay awtomatikong nagse-set up ng Python at Node.js environment
|
||||
- Buksan ang repositoryo sa Codespace sa pamamagitan ng GitHub UI
|
||||
- Ang lahat ng dependencies ay awtomatikong naka-install
|
||||
|
||||
## Mga Alituntunin sa Pull Request
|
||||
|
||||
### Bago Mag-submit
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Format ng PR Title
|
||||
- Gumamit ng malinaw, deskriptibong mga pamagat
|
||||
- Format: `[Component] Maikling paglalarawan`
|
||||
- Mga Halimbawa:
|
||||
- `[Lesson 7] Ayusin ang Python notebook import error`
|
||||
- `[Quiz App] Magdagdag ng German translation`
|
||||
- `[Docs] I-update ang README na may bagong prerequisites`
|
||||
|
||||
### Mga Kinakailangang Pag-check
|
||||
- Siguraduhing tumatakbo ang lahat ng code nang walang error
|
||||
- Tiyakin na ang mga notebook ay ganap na na-eexecute
|
||||
- Kumpirmahin na matagumpay ang pag-build ng Vue.js apps
|
||||
- Suriin na gumagana ang mga link ng dokumentasyon
|
||||
- Subukan ang aplikasyon ng pagsusulit kung binago
|
||||
- Siguraduhin na ang mga pagsasalin ay may pare-parehong estruktura
|
||||
|
||||
### Mga Alituntunin sa Kontribusyon
|
||||
- Sundin ang umiiral na estilo ng code at mga pattern
|
||||
- Magdagdag ng mga paliwanag na komento para sa kumplikadong lohika
|
||||
- I-update ang kaugnay na dokumentasyon
|
||||
- Subukan ang mga pagbabago sa iba't ibang module ng aralin kung naaangkop
|
||||
- Suriin ang CONTRIBUTING.md file
|
||||
|
||||
## Karagdagang Tala
|
||||
|
||||
### Karaniwang Ginagamit na Mga Library
|
||||
- **pandas**: Manipulasyon at pagsusuri ng data
|
||||
- **numpy**: Numerical computing
|
||||
- **matplotlib**: Visualisasyon at pag-plot ng data
|
||||
- **seaborn**: Statistical data visualization (ilang aralin)
|
||||
- **scikit-learn**: Machine learning (mga advanced na aralin)
|
||||
|
||||
### Paggamit ng Mga Data File
|
||||
- Ang mga data file ay matatagpuan sa `data/` folder o mga direktoryo na partikular sa aralin
|
||||
- Karamihan sa mga notebook ay inaasahan ang mga data file sa mga relative na path
|
||||
- Ang mga CSV file ang pangunahing format ng data
|
||||
- Ang ilang aralin ay gumagamit ng JSON para sa mga halimbawa ng non-relational na data
|
||||
|
||||
### Suporta sa Multi-Wika
|
||||
- 40+ na pagsasalin ng wika sa pamamagitan ng automated na GitHub Actions
|
||||
- Workflow ng pagsasalin sa `.github/workflows/co-op-translator.yml`
|
||||
- Ang mga pagsasalin ay nasa `translations/` folder na may mga code ng wika
|
||||
- Ang mga pagsasalin ng pagsusulit ay nasa `quiz-app/src/assets/translations/`
|
||||
|
||||
### Mga Opsyon sa Development Environment
|
||||
1. **Local Development**: Mag-install ng Python, Jupyter, Node.js nang lokal
|
||||
2. **GitHub Codespaces**: Cloud-based na instant development environment
|
||||
3. **VS Code Dev Containers**: Lokal na container-based na development
|
||||
4. **Binder**: I-launch ang mga notebook sa cloud (kung naka-configure)
|
||||
|
||||
### Mga Alituntunin sa Nilalaman ng Aralin
|
||||
- Ang bawat aralin ay standalone ngunit bumubuo sa mga naunang konsepto
|
||||
- Ang mga pre-lesson quiz ay sumusubok sa naunang kaalaman
|
||||
- Ang mga post-lesson quiz ay nagpapatibay ng pagkatuto
|
||||
- Ang mga gawain ay nagbibigay ng praktikal na pagsasanay
|
||||
- Ang mga sketchnotes ay nagbibigay ng visual na buod
|
||||
|
||||
### Pag-troubleshoot ng Karaniwang Mga Isyu
|
||||
|
||||
**Mga Isyu sa Jupyter Kernel:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Mga Pagkabigo sa npm Install:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Mga Error sa Import sa Notebook:**
|
||||
- Siguraduhing naka-install ang lahat ng kinakailangang library
|
||||
- Suriin ang compatibility ng bersyon ng Python (inirerekomenda ang Python 3.7+)
|
||||
- Tiyakin na naka-activate ang virtual environment
|
||||
|
||||
**Hindi Naglo-load ang Docsify:**
|
||||
- Siguraduhing nagseserbisyo mula sa root ng repositoryo
|
||||
- Suriin na umiiral ang `index.html`
|
||||
- Tiyakin ang tamang network access (port 3000)
|
||||
|
||||
### Mga Pagsasaalang-alang sa Performance
|
||||
- Ang malalaking dataset ay maaaring tumagal ng oras upang mag-load sa mga notebook
|
||||
- Ang pag-render ng visualisasyon ay maaaring mabagal para sa mga kumplikadong plot
|
||||
- Ang Vue.js dev server ay nagbibigay-daan sa hot-reload para sa mabilis na iterasyon
|
||||
- Ang mga production build ay na-optimize at minified
|
||||
|
||||
### Mga Tala sa Seguridad
|
||||
- Walang sensitibong data o mga kredensyal ang dapat i-commit
|
||||
- Gumamit ng environment variables para sa anumang API keys sa mga cloud lessons
|
||||
- Ang mga aralin na may kaugnayan sa Azure ay maaaring mangailangan ng mga kredensyal ng Azure account
|
||||
- Panatilihing updated ang mga dependencies para sa mga security patch
|
||||
|
||||
## Pag-aambag sa Mga Pagsasalin
|
||||
- Ang mga automated na pagsasalin ay pinamamahalaan sa pamamagitan ng GitHub Actions
|
||||
- Malugod na tinatanggap ang mga manu-manong pagwawasto para sa katumpakan ng pagsasalin
|
||||
- Sundin ang umiiral na estruktura ng folder ng pagsasalin
|
||||
- I-update ang mga link ng pagsusulit upang isama ang parameter ng wika: `?loc=fr`
|
||||
- Subukan ang mga isinaling aralin para sa tamang pag-render
|
||||
|
||||
## Kaugnay na Mga Mapagkukunan
|
||||
- Pangunahing kurikulum: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Discussion Forum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Iba pang kurikulum ng Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Pagpapanatili ng Proyekto
|
||||
- Regular na pag-update upang mapanatiling kasalukuyan ang nilalaman
|
||||
- Malugod na tinatanggap ang mga kontribusyon ng komunidad
|
||||
- Ang mga isyu ay sinusubaybayan sa GitHub
|
||||
- Ang mga PR ay sinusuri ng mga tagapangalaga ng kurikulum
|
||||
- Buwanang pagsusuri at pag-update ng nilalaman
|
||||
|
||||
---
|
||||
|
||||
**Paunawa**:
|
||||
Ang dokumentong ito ay isinalin gamit ang AI translation service na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't sinisikap naming maging tumpak, mangyaring tandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa kanyang katutubong wika ang dapat ituring na opisyal na sanggunian. Para sa mahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na dulot ng paggamit ng pagsasaling ito.
|
||||
@ -0,0 +1,372 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:04:09+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "ur"
|
||||
}
|
||||
-->
|
||||
# اے جی ای این ٹی ایس۔ایم ڈی
|
||||
|
||||
## پروجیکٹ کا جائزہ
|
||||
|
||||
ڈیٹا سائنس فار بیگنرز مائیکروسافٹ ایزور کلاؤڈ ایڈووکیٹس کے ذریعہ تخلیق کردہ ایک جامع 10 ہفتوں، 20 اسباق پر مشتمل نصاب ہے۔ یہ ریپوزیٹری ایک تعلیمی وسیلہ ہے جو پروجیکٹ پر مبنی اسباق کے ذریعے بنیادی ڈیٹا سائنس کے تصورات سکھاتا ہے، جس میں جیوپیٹر نوٹ بکس، انٹرایکٹو کوئزز، اور عملی اسائنمنٹس شامل ہیں۔
|
||||
|
||||
**اہم ٹیکنالوجیز:**
|
||||
- **جیوپیٹر نوٹ بکس**: Python 3 کے ساتھ بنیادی تعلیمی ذریعہ
|
||||
- **پائتھن لائبریریاں**: pandas، numpy، matplotlib ڈیٹا تجزیہ اور بصریات کے لیے
|
||||
- **Vue.js 2**: کوئز ایپلیکیشن (quiz-app فولڈر)
|
||||
- **Docsify**: آف لائن رسائی کے لیے دستاویزات سائٹ جنریٹر
|
||||
- **Node.js/npm**: جاوا اسکرپٹ اجزاء کے لیے پیکیج مینجمنٹ
|
||||
- **مارک ڈاؤن**: تمام اسباق کا مواد اور دستاویزات
|
||||
|
||||
**آرکیٹیکچر:**
|
||||
- کثیر زبانوں پر مشتمل تعلیمی ریپوزیٹری جس میں وسیع ترجمے شامل ہیں
|
||||
- اسباق کے ماڈیولز میں منظم (1-Introduction سے 6-Data-Science-In-Wild تک)
|
||||
- ہر سبق میں README، نوٹ بکس، اسائنمنٹس، اور کوئزز شامل ہیں
|
||||
- پری/پوسٹ سبق کے جائزے کے لیے اسٹینڈ الون Vue.js کوئز ایپلیکیشن
|
||||
- GitHub Codespaces اور VS Code ڈیولپمنٹ کنٹینرز کی حمایت
|
||||
|
||||
## سیٹ اپ کمانڈز
|
||||
|
||||
### ریپوزیٹری سیٹ اپ
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### پائتھن ماحول سیٹ اپ
|
||||
```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
|
||||
```
|
||||
|
||||
### کوئز ایپلیکیشن سیٹ اپ
|
||||
```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 دستاویزات سرور
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### بصری منصوبوں کا سیٹ اپ
|
||||
معنی خیز بصریات جیسے منصوبوں کے لیے (سبق 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
|
||||
```
|
||||
|
||||
## ترقیاتی ورک فلو
|
||||
|
||||
### جیوپیٹر نوٹ بکس کے ساتھ کام کرنا
|
||||
1. ریپوزیٹری روٹ میں جیوپیٹر شروع کریں: `jupyter notebook`
|
||||
2. مطلوبہ سبق فولڈر پر جائیں
|
||||
3. `.ipynb` فائلز کھولیں اور مشقیں کریں
|
||||
4. نوٹ بکس وضاحتوں اور کوڈ سیلز کے ساتھ خود مختار ہیں
|
||||
5. زیادہ تر نوٹ بکس pandas، numpy، اور matplotlib استعمال کرتے ہیں - یقینی بنائیں کہ یہ انسٹال ہیں
|
||||
|
||||
### سبق کی ساخت
|
||||
ہر سبق عام طور پر شامل ہوتا ہے:
|
||||
- `README.md` - مرکزی سبق کا مواد نظریہ اور مثالوں کے ساتھ
|
||||
- `notebook.ipynb` - عملی جیوپیٹر نوٹ بک مشقیں
|
||||
- `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)
|
||||
|
||||
## ٹیسٹنگ ہدایات
|
||||
|
||||
### کوئز ایپلیکیشن ٹیسٹنگ
|
||||
```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
|
||||
```
|
||||
|
||||
### نوٹ بک ٹیسٹنگ
|
||||
- نوٹ بکس کے لیے کوئی خودکار ٹیسٹ فریم ورک موجود نہیں ہے
|
||||
- دستی توثیق: تمام سیلز کو ترتیب میں چلائیں تاکہ کوئی غلطی نہ ہو
|
||||
- ڈیٹا فائلز کی رسائی اور آؤٹ پٹس کی درستگی کی تصدیق کریں
|
||||
- بصریات کی درست رینڈرنگ کو چیک کریں
|
||||
|
||||
### دستاویزات ٹیسٹنگ
|
||||
```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
|
||||
```
|
||||
|
||||
### کوڈ کوالٹی چیکس
|
||||
```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
|
||||
```
|
||||
|
||||
## کوڈ اسٹائل گائیڈ لائنز
|
||||
|
||||
### پائتھن (جیوپیٹر نوٹ بکس)
|
||||
- پائتھن کوڈ کے لیے PEP 8 اسٹائل گائیڈ لائنز پر عمل کریں
|
||||
- واضح متغیر نام استعمال کریں جو تجزیہ کیے جانے والے ڈیٹا کی وضاحت کریں
|
||||
- کوڈ سیلز سے پہلے وضاحتوں کے ساتھ مارک ڈاؤن سیلز شامل کریں
|
||||
- کوڈ سیلز کو ایک ہی تصور یا آپریشن پر مرکوز رکھیں
|
||||
- ڈیٹا ہیرا پھیری کے لیے pandas، بصریات کے لیے matplotlib استعمال کریں
|
||||
- عام درآمد کا نمونہ:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
### جاوا اسکرپٹ/Vue.js
|
||||
- Vue.js 2 اسٹائل گائیڈ اور بہترین طریقوں پر عمل کریں
|
||||
- ESLint کنفیگریشن `quiz-app/package.json` میں
|
||||
- Vue سنگل فائل اجزاء (.vue فائلز) استعمال کریں
|
||||
- جزو پر مبنی آرکیٹیکچر برقرار رکھیں
|
||||
- تبدیلیاں کرنے سے پہلے `npm run lint` چلائیں
|
||||
|
||||
### مارک ڈاؤن دستاویزات
|
||||
- واضح سرخیوں کی درجہ بندی استعمال کریں (# ## ### وغیرہ)
|
||||
- زبان کے وضاحت کنندہ کے ساتھ کوڈ بلاکس شامل کریں
|
||||
- تصاویر کے لیے alt متن شامل کریں
|
||||
- متعلقہ اسباق اور وسائل کے لنکس شامل کریں
|
||||
- پڑھنے کے لیے لائن کی لمبائی مناسب رکھیں
|
||||
|
||||
### فائل تنظیم
|
||||
- سبق کا مواد نمبر والے فولڈرز میں (01-defining-data-science، وغیرہ)
|
||||
- حل مخصوص `solution/` سب فولڈرز میں
|
||||
- ترجمے انگریزی ڈھانچے کو `translations/` فولڈر میں آئینہ دار کرتے ہیں
|
||||
- ڈیٹا فائلز کو `data/` یا سبق مخصوص فولڈرز میں رکھیں
|
||||
|
||||
## تعمیر اور تعیناتی
|
||||
|
||||
### کوئز ایپلیکیشن تعیناتی
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Azure Static Web Apps تعیناتی
|
||||
کوئز ایپ کو Azure Static Web Apps پر تعینات کیا جا سکتا ہے:
|
||||
1. Azure Static Web App ریسورس بنائیں
|
||||
2. GitHub ریپوزیٹری سے جڑیں
|
||||
3. تعمیر کی ترتیبات کو ترتیب دیں:
|
||||
- ایپ مقام: `quiz-app`
|
||||
- آؤٹ پٹ مقام: `dist`
|
||||
4. GitHub Actions ورک فلو پش پر خودکار تعیناتی کرے گا
|
||||
|
||||
### دستاویزات سائٹ
|
||||
```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
|
||||
- ریپوزیٹری میں ڈیولپمنٹ کنٹینر کنفیگریشن شامل ہے
|
||||
- Codespaces خود بخود پائتھن اور Node.js ماحول سیٹ اپ کرتا ہے
|
||||
- GitHub UI کے ذریعے ریپوزیٹری کو Codespace میں کھولیں
|
||||
- تمام انحصار خود بخود انسٹال ہو جاتے ہیں
|
||||
|
||||
## پل ریکویسٹ گائیڈ لائنز
|
||||
|
||||
### جمع کرانے سے پہلے
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### پی آر عنوان کی شکل
|
||||
- واضح، وضاحتی عنوانات استعمال کریں
|
||||
- فارمیٹ: `[Component] مختصر وضاحت`
|
||||
- مثالیں:
|
||||
- `[Lesson 7] Python نوٹ بک درآمد کی غلطی کو درست کریں`
|
||||
- `[Quiz App] جرمن ترجمہ شامل کریں`
|
||||
- `[Docs] نئی ضروریات کے ساتھ README کو اپ ڈیٹ کریں`
|
||||
|
||||
### مطلوبہ چیکس
|
||||
- یقینی بنائیں کہ تمام کوڈ بغیر کسی غلطی کے چلتا ہے
|
||||
- تصدیق کریں کہ نوٹ بکس مکمل طور پر عمل کرتے ہیں
|
||||
- تصدیق کریں کہ Vue.js ایپس کامیابی سے تعمیر ہوتی ہیں
|
||||
- چیک کریں کہ دستاویزات کے لنکس کام کرتے ہیں
|
||||
- اگر ترمیم کی گئی ہو تو کوئز ایپلیکیشن کی جانچ کریں
|
||||
- تصدیق کریں کہ ترجمے مستقل ڈھانچے کو برقرار رکھتے ہیں
|
||||
|
||||
### ترجمہ میں تعاون
|
||||
- موجودہ کوڈ اسٹائل اور پیٹرنز پر عمل کریں
|
||||
- پیچیدہ منطق کے لیے وضاحتی تبصرے شامل کریں
|
||||
- متعلقہ دستاویزات کو اپ ڈیٹ کریں
|
||||
- اگر قابل اطلاق ہو تو مختلف سبق ماڈیولز میں تبدیلیوں کی جانچ کریں
|
||||
- CONTRIBUTING.md فائل کا جائزہ لیں
|
||||
|
||||
## اضافی نوٹس
|
||||
|
||||
### عام استعمال شدہ لائبریریاں
|
||||
- **pandas**: ڈیٹا ہیرا پھیری اور تجزیہ
|
||||
- **numpy**: عددی کمپیوٹنگ
|
||||
- **matplotlib**: ڈیٹا بصریات اور پلاٹنگ
|
||||
- **seaborn**: شماریاتی ڈیٹا بصریات (کچھ اسباق)
|
||||
- **scikit-learn**: مشین لرننگ (اعلی درجے کے اسباق)
|
||||
|
||||
### ڈیٹا فائلز کے ساتھ کام کرنا
|
||||
- ڈیٹا فائلز `data/` فولڈر یا سبق مخصوص ڈائریکٹریز میں واقع ہیں
|
||||
- زیادہ تر نوٹ بکس ڈیٹا فائلز کو رشتہ دار راستوں میں توقع کرتے ہیں
|
||||
- CSV فائلز بنیادی ڈیٹا فارمیٹ ہیں
|
||||
- کچھ اسباق غیر رشتہ دار ڈیٹا مثالوں کے لیے JSON استعمال کرتے ہیں
|
||||
|
||||
### کثیر لسانی حمایت
|
||||
- 40+ زبانوں کے ترجمے خودکار GitHub Actions کے ذریعے
|
||||
- ترجمہ ورک فلو `.github/workflows/co-op-translator.yml` میں
|
||||
- ترجمے `translations/` فولڈر میں زبان کے کوڈز کے ساتھ
|
||||
- کوئز ترجمے `quiz-app/src/assets/translations/` میں
|
||||
|
||||
### ترقیاتی ماحول کے اختیارات
|
||||
1. **مقامی ترقی**: Python، Jupyter، Node.js مقامی طور پر انسٹال کریں
|
||||
2. **GitHub Codespaces**: کلاؤڈ پر مبنی فوری ترقیاتی ماحول
|
||||
3. **VS Code Dev Containers**: مقامی کنٹینر پر مبنی ترقی
|
||||
4. **Binder**: کلاؤڈ میں نوٹ بکس لانچ کریں (اگر کنفیگر کیا گیا ہو)
|
||||
|
||||
### سبق مواد کی گائیڈ لائنز
|
||||
- ہر سبق خود مختار ہے لیکن پچھلے تصورات پر مبنی ہے
|
||||
- سبق سے پہلے کے کوئزز پہلے علم کی جانچ کرتے ہیں
|
||||
- سبق کے بعد کے کوئزز سیکھنے کو مضبوط کرتے ہیں
|
||||
- اسائنمنٹس عملی مشق فراہم کرتے ہیں
|
||||
- اسکیچ نوٹس بصری خلاصے فراہم کرتے ہیں
|
||||
|
||||
### عام مسائل کا حل
|
||||
|
||||
**جیوپیٹر کرنل کے مسائل:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**npm انسٹال کی ناکامی:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**نوٹ بکس میں درآمد کی غلطیاں:**
|
||||
- تصدیق کریں کہ تمام مطلوبہ لائبریریاں انسٹال ہیں
|
||||
- پائتھن ورژن کی مطابقت چیک کریں (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 پر ٹریک کیے گئے
|
||||
- پی آرز نصاب کے منتظمین کے ذریعے جائزہ لیا گیا
|
||||
- ماہانہ مواد کے جائزے اور اپ ڈیٹس
|
||||
|
||||
---
|
||||
|
||||
**ڈس کلیمر**:
|
||||
یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کا استعمال کرتے ہوئے ترجمہ کی گئی ہے۔ اگرچہ ہم درستگی کے لیے کوشش کرتے ہیں، براہ کرم آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا خامیاں ہو سکتی ہیں۔ اصل دستاویز کو اس کی اصل زبان میں مستند ذریعہ سمجھا جانا چاہیے۔ اہم معلومات کے لیے، پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کے لیے ہم ذمہ دار نہیں ہیں۔
|
||||
@ -0,0 +1,375 @@
|
||||
<!--
|
||||
CO_OP_TRANSLATOR_METADATA:
|
||||
{
|
||||
"original_hash": "cc2e18ab65df63e75d3619c4752e9b22",
|
||||
"translation_date": "2025-10-03T11:29:52+00:00",
|
||||
"source_file": "AGENTS.md",
|
||||
"language_code": "vi"
|
||||
}
|
||||
-->
|
||||
# AGENTS.md
|
||||
|
||||
## Tổng quan dự án
|
||||
|
||||
Data Science for Beginners là một chương trình học toàn diện kéo dài 10 tuần với 20 bài học được tạo bởi Microsoft Azure Cloud Advocates. Kho lưu trữ này là một tài nguyên học tập dạy các khái niệm cơ bản về khoa học dữ liệu thông qua các bài học dựa trên dự án, bao gồm Jupyter notebooks, bài kiểm tra tương tác và bài tập thực hành.
|
||||
|
||||
**Công nghệ chính:**
|
||||
- **Jupyter Notebooks**: Phương tiện học tập chính sử dụng Python 3
|
||||
- **Thư viện Python**: pandas, numpy, matplotlib để phân tích và trực quan hóa dữ liệu
|
||||
- **Vue.js 2**: Ứng dụng bài kiểm tra (thư mục quiz-app)
|
||||
- **Docsify**: Trình tạo trang tài liệu để truy cập ngoại tuyến
|
||||
- **Node.js/npm**: Quản lý gói cho các thành phần JavaScript
|
||||
- **Markdown**: Tất cả nội dung bài học và tài liệu
|
||||
|
||||
**Kiến trúc:**
|
||||
- Kho lưu trữ giáo dục đa ngôn ngữ với các bản dịch phong phú
|
||||
- Được cấu trúc thành các mô-đun bài học (1-Introduction đến 6-Data-Science-In-Wild)
|
||||
- Mỗi bài học bao gồm README, notebooks, bài tập và bài kiểm tra
|
||||
- Ứng dụng bài kiểm tra Vue.js độc lập để đánh giá trước/sau bài học
|
||||
- Hỗ trợ GitHub Codespaces và container phát triển VS Code
|
||||
|
||||
## Lệnh thiết lập
|
||||
|
||||
### Thiết lập kho lưu trữ
|
||||
```bash
|
||||
# Clone the repository (if not already cloned)
|
||||
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
|
||||
cd Data-Science-For-Beginners
|
||||
```
|
||||
|
||||
### Thiết lập môi trường Python
|
||||
```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
|
||||
```
|
||||
|
||||
### Thiết lập ứng dụng bài kiểm tra
|
||||
```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
|
||||
```
|
||||
|
||||
### Máy chủ tài liệu Docsify
|
||||
```bash
|
||||
# Install Docsify globally
|
||||
npm install -g docsify-cli
|
||||
|
||||
# Serve documentation locally
|
||||
docsify serve
|
||||
|
||||
# Documentation will be available at localhost:3000
|
||||
```
|
||||
|
||||
### Thiết lập dự án trực quan hóa
|
||||
Đối với các dự án trực quan hóa như meaningful-visualizations (bài học 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
|
||||
```
|
||||
|
||||
|
||||
## Quy trình phát triển
|
||||
|
||||
### Làm việc với Jupyter Notebooks
|
||||
1. Khởi động Jupyter tại thư mục gốc của kho lưu trữ: `jupyter notebook`
|
||||
2. Điều hướng đến thư mục bài học mong muốn
|
||||
3. Mở các tệp `.ipynb` để làm bài tập
|
||||
4. Notebooks là các tài liệu tự chứa với giải thích và ô mã
|
||||
5. Hầu hết các notebooks sử dụng pandas, numpy và matplotlib - đảm bảo đã cài đặt chúng
|
||||
|
||||
### Cấu trúc bài học
|
||||
Mỗi bài học thường bao gồm:
|
||||
- `README.md` - Nội dung chính của bài học với lý thuyết và ví dụ
|
||||
- `notebook.ipynb` - Bài tập thực hành với Jupyter notebook
|
||||
- `assignment.ipynb` hoặc `assignment.md` - Bài tập thực hành
|
||||
- Thư mục `solution/` - Notebook và mã giải pháp
|
||||
- Thư mục `images/` - Tài liệu hình ảnh hỗ trợ
|
||||
|
||||
### Phát triển ứng dụng bài kiểm tra
|
||||
- Ứng dụng Vue.js 2 với tính năng tải lại nóng trong quá trình phát triển
|
||||
- Các bài kiểm tra được lưu trong `quiz-app/src/assets/translations/`
|
||||
- Mỗi ngôn ngữ có thư mục dịch riêng (en, fr, es, v.v.)
|
||||
- Số thứ tự bài kiểm tra bắt đầu từ 0 và lên đến 39 (tổng cộng 40 bài kiểm tra)
|
||||
|
||||
### Thêm bản dịch
|
||||
- Các bản dịch được đặt trong thư mục `translations/` tại thư mục gốc của kho lưu trữ
|
||||
- Mỗi ngôn ngữ có cấu trúc bài học đầy đủ giống với tiếng Anh
|
||||
- Dịch tự động thông qua GitHub Actions (co-op-translator.yml)
|
||||
|
||||
## Hướng dẫn kiểm tra
|
||||
|
||||
### Kiểm tra ứng dụng bài kiểm tra
|
||||
```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
|
||||
```
|
||||
|
||||
### Kiểm tra notebook
|
||||
- Không có khung kiểm tra tự động cho notebooks
|
||||
- Xác thực thủ công: Chạy tất cả các ô theo thứ tự để đảm bảo không có lỗi
|
||||
- Xác minh các tệp dữ liệu có thể truy cập và đầu ra được tạo đúng cách
|
||||
- Kiểm tra rằng các hình ảnh trực quan được hiển thị đúng
|
||||
|
||||
### Kiểm tra tài liệu
|
||||
```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
|
||||
```
|
||||
|
||||
### Kiểm tra chất lượng mã
|
||||
```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
|
||||
```
|
||||
|
||||
|
||||
## Hướng dẫn về phong cách mã
|
||||
|
||||
### Python (Jupyter Notebooks)
|
||||
- Tuân theo hướng dẫn phong cách PEP 8 cho mã Python
|
||||
- Sử dụng tên biến rõ ràng để giải thích dữ liệu đang được phân tích
|
||||
- Bao gồm các ô markdown với giải thích trước các ô mã
|
||||
- Giữ các ô mã tập trung vào một khái niệm hoặc thao tác duy nhất
|
||||
- Sử dụng pandas để xử lý dữ liệu, matplotlib để trực quan hóa
|
||||
- Mẫu nhập phổ biến:
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
```
|
||||
|
||||
|
||||
### JavaScript/Vue.js
|
||||
- Tuân theo hướng dẫn phong cách Vue.js 2 và các thực hành tốt nhất
|
||||
- Cấu hình ESLint trong `quiz-app/package.json`
|
||||
- Sử dụng các thành phần đơn tệp Vue (.vue files)
|
||||
- Duy trì kiến trúc dựa trên thành phần
|
||||
- Chạy `npm run lint` trước khi commit thay đổi
|
||||
|
||||
### Tài liệu Markdown
|
||||
- Sử dụng hệ thống tiêu đề rõ ràng (# ## ### v.v.)
|
||||
- Bao gồm các khối mã với chỉ định ngôn ngữ
|
||||
- Thêm văn bản thay thế cho hình ảnh
|
||||
- Liên kết đến các bài học và tài nguyên liên quan
|
||||
- Giữ độ dài dòng hợp lý để dễ đọc
|
||||
|
||||
### Tổ chức tệp
|
||||
- Nội dung bài học trong các thư mục được đánh số (01-defining-data-science, v.v.)
|
||||
- Giải pháp trong các thư mục con `solution/` chuyên dụng
|
||||
- Các bản dịch phản ánh cấu trúc tiếng Anh trong thư mục `translations/`
|
||||
- Giữ các tệp dữ liệu trong thư mục `data/` hoặc các thư mục bài học cụ thể
|
||||
|
||||
## Xây dựng và triển khai
|
||||
|
||||
### Triển khai ứng dụng bài kiểm tra
|
||||
```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.)
|
||||
```
|
||||
|
||||
### Triển khai Azure Static Web Apps
|
||||
Ứng dụng quiz-app có thể được triển khai lên Azure Static Web Apps:
|
||||
1. Tạo tài nguyên Azure Static Web App
|
||||
2. Kết nối với kho lưu trữ GitHub
|
||||
3. Cấu hình cài đặt xây dựng:
|
||||
- Vị trí ứng dụng: `quiz-app`
|
||||
- Vị trí đầu ra: `dist`
|
||||
4. Workflow GitHub Actions sẽ tự động triển khai khi có thay đổi
|
||||
|
||||
### Trang tài liệu
|
||||
```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
|
||||
- Kho lưu trữ bao gồm cấu hình container phát triển
|
||||
- Codespaces tự động thiết lập môi trường Python và Node.js
|
||||
- Mở kho lưu trữ trong Codespace qua giao diện GitHub
|
||||
- Tất cả các phụ thuộc được cài đặt tự động
|
||||
|
||||
## Hướng dẫn Pull Request
|
||||
|
||||
### Trước khi gửi
|
||||
```bash
|
||||
# For Vue.js changes in quiz-app
|
||||
cd quiz-app
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# Test changes locally
|
||||
npm run serve
|
||||
```
|
||||
|
||||
### Định dạng tiêu đề PR
|
||||
- Sử dụng tiêu đề rõ ràng, mô tả
|
||||
- Định dạng: `[Component] Mô tả ngắn gọn`
|
||||
- Ví dụ:
|
||||
- `[Lesson 7] Sửa lỗi nhập notebook Python`
|
||||
- `[Quiz App] Thêm bản dịch tiếng Đức`
|
||||
- `[Docs] Cập nhật README với các yêu cầu mới`
|
||||
|
||||
### Kiểm tra bắt buộc
|
||||
- Đảm bảo tất cả mã chạy không có lỗi
|
||||
- Xác minh các notebook thực thi hoàn toàn
|
||||
- Xác nhận các ứng dụng Vue.js xây dựng thành công
|
||||
- Kiểm tra rằng các liên kết tài liệu hoạt động
|
||||
- Kiểm tra ứng dụng bài kiểm tra nếu có thay đổi
|
||||
- Xác minh các bản dịch duy trì cấu trúc nhất quán
|
||||
|
||||
### Hướng dẫn đóng góp
|
||||
- Tuân theo phong cách và mẫu mã hiện có
|
||||
- Thêm các bình luận giải thích cho logic phức tạp
|
||||
- Cập nhật tài liệu liên quan
|
||||
- Kiểm tra thay đổi trên các mô-đun bài học khác nhau nếu áp dụng
|
||||
- Xem lại tệp CONTRIBUTING.md
|
||||
|
||||
## Ghi chú bổ sung
|
||||
|
||||
### Các thư viện thường dùng
|
||||
- **pandas**: Xử lý và phân tích dữ liệu
|
||||
- **numpy**: Tính toán số học
|
||||
- **matplotlib**: Trực quan hóa và vẽ biểu đồ dữ liệu
|
||||
- **seaborn**: Trực quan hóa dữ liệu thống kê (một số bài học)
|
||||
- **scikit-learn**: Học máy (bài học nâng cao)
|
||||
|
||||
### Làm việc với tệp dữ liệu
|
||||
- Các tệp dữ liệu nằm trong thư mục `data/` hoặc các thư mục bài học cụ thể
|
||||
- Hầu hết các notebook mong đợi tệp dữ liệu ở đường dẫn tương đối
|
||||
- Tệp CSV là định dạng dữ liệu chính
|
||||
- Một số bài học sử dụng JSON cho ví dụ dữ liệu phi quan hệ
|
||||
|
||||
### Hỗ trợ đa ngôn ngữ
|
||||
- Hơn 40 bản dịch ngôn ngữ thông qua GitHub Actions tự động
|
||||
- Quy trình dịch trong `.github/workflows/co-op-translator.yml`
|
||||
- Các bản dịch trong thư mục `translations/` với mã ngôn ngữ
|
||||
- Dịch bài kiểm tra trong `quiz-app/src/assets/translations/`
|
||||
|
||||
### Tùy chọn môi trường phát triển
|
||||
1. **Phát triển cục bộ**: Cài đặt Python, Jupyter, Node.js trên máy
|
||||
2. **GitHub Codespaces**: Môi trường phát triển tức thì trên đám mây
|
||||
3. **VS Code Dev Containers**: Phát triển dựa trên container cục bộ
|
||||
4. **Binder**: Khởi chạy notebook trên đám mây (nếu được cấu hình)
|
||||
|
||||
### Hướng dẫn nội dung bài học
|
||||
- Mỗi bài học độc lập nhưng xây dựng dựa trên các khái niệm trước đó
|
||||
- Bài kiểm tra trước bài học kiểm tra kiến thức trước đó
|
||||
- Bài kiểm tra sau bài học củng cố kiến thức
|
||||
- Bài tập cung cấp thực hành thực tế
|
||||
- Sketchnotes cung cấp tóm tắt trực quan
|
||||
|
||||
### Xử lý sự cố thường gặp
|
||||
|
||||
**Vấn đề kernel Jupyter:**
|
||||
```bash
|
||||
# Ensure correct kernel is installed
|
||||
python -m ipykernel install --user --name=datascience
|
||||
```
|
||||
|
||||
**Lỗi cài đặt npm:**
|
||||
```bash
|
||||
# Clear npm cache and retry
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**Lỗi nhập trong notebook:**
|
||||
- Xác minh tất cả các thư viện cần thiết đã được cài đặt
|
||||
- Kiểm tra khả năng tương thích phiên bản Python (khuyến nghị Python 3.7+)
|
||||
- Đảm bảo môi trường ảo đã được kích hoạt
|
||||
|
||||
**Docsify không tải:**
|
||||
- Xác minh bạn đang phục vụ từ thư mục gốc của kho lưu trữ
|
||||
- Kiểm tra rằng `index.html` tồn tại
|
||||
- Đảm bảo truy cập mạng đúng cách (cổng 3000)
|
||||
|
||||
### Cân nhắc về hiệu suất
|
||||
- Các tập dữ liệu lớn có thể mất thời gian để tải trong notebook
|
||||
- Việc hiển thị hình ảnh trực quan có thể chậm đối với các biểu đồ phức tạp
|
||||
- Máy chủ phát triển Vue.js cho phép tải lại nóng để lặp nhanh
|
||||
- Các bản dựng sản xuất được tối ưu hóa và giảm thiểu
|
||||
|
||||
### Ghi chú bảo mật
|
||||
- Không nên commit dữ liệu nhạy cảm hoặc thông tin đăng nhập
|
||||
- Sử dụng biến môi trường cho bất kỳ khóa API nào trong các bài học đám mây
|
||||
- Các bài học liên quan đến Azure có thể yêu cầu thông tin đăng nhập tài khoản Azure
|
||||
- Giữ các phụ thuộc được cập nhật để vá lỗi bảo mật
|
||||
|
||||
## Đóng góp cho bản dịch
|
||||
- Các bản dịch tự động được quản lý thông qua GitHub Actions
|
||||
- Chào đón các chỉnh sửa thủ công để đảm bảo độ chính xác của bản dịch
|
||||
- Tuân theo cấu trúc thư mục dịch hiện có
|
||||
- Cập nhật liên kết bài kiểm tra để bao gồm tham số ngôn ngữ: `?loc=fr`
|
||||
- Kiểm tra các bài học đã dịch để đảm bảo hiển thị đúng
|
||||
|
||||
## Tài nguyên liên quan
|
||||
- Chương trình chính: https://aka.ms/datascience-beginners
|
||||
- Microsoft Learn: https://docs.microsoft.com/learn/
|
||||
- Student Hub: https://docs.microsoft.com/learn/student-hub
|
||||
- Diễn đàn thảo luận: https://github.com/microsoft/Data-Science-For-Beginners/discussions
|
||||
- Các chương trình học khác của Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners
|
||||
|
||||
## Bảo trì dự án
|
||||
- Cập nhật thường xuyên để giữ nội dung luôn mới
|
||||
- Chào đón đóng góp từ cộng đồng
|
||||
- Các vấn đề được theo dõi trên GitHub
|
||||
- PRs được xem xét bởi các nhà quản lý chương trình học
|
||||
- Xem xét và cập nhật nội dung hàng tháng
|
||||
|
||||
---
|
||||
|
||||
**Tuyên bố miễn trừ trách nhiệm**:
|
||||
Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ bản địa nên được coi là nguồn thông tin chính thức. Đối với các thông tin quan trọng, khuyến nghị sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm cho bất kỳ sự hiểu lầm hoặc diễn giải sai nào phát sinh từ việc sử dụng bản dịch này.
|
||||
Loading…
Reference in new issue