10 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

專案概述

《初學者的數據科學》是一個由 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 開發容器

設置指令

存儲庫設置

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

Python 環境設置

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install common data science libraries (no requirements.txt exists)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

測驗應用程式設置

# Navigate to quiz app
cd quiz-app

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint and fix files
npm run lint

Docsify 文件伺服器

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

可視化項目設置

針對像 meaningful-visualizations（第 13 課）這樣的可視化項目：

# Navigate to starter or solution folder
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint files
npm run lint

開發工作流程

使用 Jupyter 筆記本

在存儲庫根目錄啟動 Jupyter：jupyter notebook
導航到所需的課程資料夾
打開 .ipynb 文件進行練習
筆記本是自包含的，包含解釋和代碼單元
大多數筆記本使用 pandas、numpy 和 matplotlib，請確保已安裝這些庫

課程結構

每課通常包含：

README.md - 主要課程內容，包含理論和範例
notebook.ipynb - 實作 Jupyter 筆記本練習
assignment.ipynb 或 assignment.md - 練習作業
solution/ 資料夾 - 解答筆記本和代碼
images/ 資料夾 - 支援的視覺材料

測驗應用程式開發

Vue.js 2 應用程式，開發期間支援熱重載
測驗存儲於 quiz-app/src/assets/translations/
每種語言有自己的翻譯資料夾（en、fr、es 等）
測驗編號從 0 開始，最多到 39（共 40 個測驗）

添加翻譯

翻譯存放於存儲庫根目錄的 translations/ 資料夾
每種語言的課程結構與英文完全鏡像
通過 GitHub Actions 自動翻譯（co-op-translator.yml）

測試指導

測驗應用程式測試

cd quiz-app

# Run lint checks
npm run lint

# Test build process
npm run build

# Manual testing: Start dev server and verify quiz functionality
npm run serve

筆記本測試

筆記本沒有自動化測試框架
手動驗證：按順序運行所有單元以確保無錯誤
確認數據文件可訪問且輸出正確生成
檢查可視化是否正確渲染

文件測試

# Verify Docsify renders correctly
docsify serve

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

代碼質量檢查

# Vue.js projects (quiz-app and visualization projects)
cd quiz-app  # or visualization project folder
npm run lint

# Python notebooks - manual verification recommended
# Ensure imports work and cells execute without errors

代碼風格指南

Python（Jupyter 筆記本）

遵循 PEP 8 代碼風格指南
使用清晰的變數名稱，說明正在分析的數據
在代碼單元之前包含解釋的 Markdown 單元
代碼單元應專注於單一概念或操作
使用 pandas 進行數據操作，matplotlib 進行可視化

常見的導入模式：

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 文件

使用清晰的標題層次結構（# ## ### 等）
包含帶語言指定的代碼塊
為圖片添加替代文字
鏈接相關課程和資源
保持合理的行長以提高可讀性

文件組織

課程內容存放於編號資料夾（01-defining-data-science 等）
解答存放於專用的 solution/ 子資料夾
翻譯在 translations/ 資料夾中鏡像英文結構
數據文件存放於 data/ 或課程專用資料夾

構建和部署

測驗應用程式部署

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 靜態 Web 應用部署

測驗應用程式可部署到 Azure 靜態 Web 應用：

創建 Azure 靜態 Web 應用資源
連接到 GitHub 存儲庫
配置構建設置：
- 應用位置：quiz-app
- 輸出位置：dist
GitHub Actions 工作流程會在推送時自動部署

文件站點

# Build PDF from Docsify (optional)
npm run convert

# Docsify documentation is served directly from markdown files
# No build step required for deployment
# Deploy repository to static hosting with Docsify

GitHub Codespaces

存儲庫包含開發容器配置
Codespaces 自動設置 Python 和 Node.js 環境
通過 GitHub UI 打開存儲庫中的 Codespace
所有依賴項自動安裝

拉取請求指南

提交前

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

開發環境選項

本地開發：本地安裝 Python、Jupyter、Node.js
GitHub Codespaces：基於雲端的即時開發環境
VS Code 開發容器：基於容器的本地開發
Binder：在雲端啟動筆記本（如已配置）

課程內容指南

每課是獨立的，但建立在之前概念之上
課前測驗測試先前知識
課後測驗加強學習
作業提供實作練習
Sketchnotes 提供視覺摘要

常見問題排查

Jupyter 核心問題：

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

npm 安裝失敗：

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

筆記本導入錯誤：

確認已安裝所有必要庫
檢查 Python 版本兼容性（建議使用 Python 3.7+）
確保虛擬環境已啟動

Docsify 無法加載：

確認您從存儲庫根目錄提供服務
檢查 index.html 是否存在
確保網絡訪問正常（端口 3000）

性能考量

大型數據集可能需要較長時間加載到筆記本中
複雜圖表的可視化渲染可能較慢
Vue.js 開發伺服器啟用熱重載以快速迭代
生產構建已優化並縮小

安全注意事項

不應提交敏感數據或憑證
在雲端課程中使用環境變數存儲 API 密鑰
與 Azure 相關的課程可能需要 Azure 帳戶憑證
保持依賴項更新以獲得安全修補

翻譯貢獻

通過 GitHub Actions 管理自動翻譯
歡迎手動修正以提高翻譯準確性
遵循現有翻譯資料夾結構
更新測驗鏈接以包含語言參數：?loc=fr
測試翻譯課程以確保正確渲染

專案維護

定期更新以保持內容最新
歡迎社群貢獻
問題在 GitHub 上追蹤
PR 由課程維護者審核
每月進行內容審查和更新

免責聲明：
本文件已使用 AI 翻譯服務 Co-op Translator 進行翻譯。儘管我們致力於提供準確的翻譯，請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於關鍵資訊，建議使用專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或錯誤解釋不承擔責任。

10 KiB Raw Permalink Blame History Unescape Escape