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开始，总计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 风格指南编写 Python 代码
使用清晰的变量名，解释所分析的数据
在代码单元之前包含解释性的 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 标题格式

使用清晰、描述性的标题
格式：[组件] 简短描述
示例：
- [第7课] 修复 Python 笔记本导入错误
- [测验应用] 添加德语翻译
- [文档] 更新 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