12 KiB

Raw Blame History

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

# 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

# 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

# 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

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

# 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

Mulakan Jupyter di akar repositori: jupyter notebook
Navigasi ke folder pelajaran yang diingini
Buka fail .ipynb untuk menjalankan latihan
Notebooks adalah berdiri sendiri dengan penjelasan dan sel kod
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

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

# 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

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

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

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:

Buat sumber Azure Static Web App
Sambungkan ke repositori GitHub
Konfigurasi tetapan pembinaan:
- Lokasi aplikasi: quiz-app
- Lokasi output: dist
Aliran kerja GitHub Actions akan menerapkan secara automatik pada push

Laman Dokumentasi

# 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

# 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

Pembangunan Tempatan: Pasang Python, Jupyter, Node.js secara tempatan
GitHub Codespaces: Persekitaran pembangunan segera berasaskan awan
Kontena Dev VS Code: Pembangunan berasaskan kontena tempatan
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:

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

Kegagalan Pemasangan npm:

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

12 KiB Raw Blame History