14 KiB

Raw Permalink Blame History

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

# 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

# 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

# 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

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

# 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

Démarrez Jupyter à la racine du dépôt : jupyter notebook
Naviguez vers le dossier de la leçon souhaitée
Ouvrez les fichiers .ipynb pour travailler sur les exercices
Les notebooks sont autonomes avec des explications et des cellules de code
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

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

# 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

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

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

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 :

Créez une ressource Azure Static Web App
Connectez-vous au dépôt GitHub
Configurez les paramètres de construction :
- Emplacement de l'application : quiz-app
- Emplacement de sortie : dist
Le workflow GitHub Actions déploiera automatiquement lors d'un push

Site de documentation

# 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

# 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

Développement local : Installez Python, Jupyter, Node.js localement
GitHub Codespaces : Environnement de développement instantané basé sur le cloud
Conteneurs de développement VS Code : Développement local basé sur des conteneurs
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 :

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

Échecs d'installation npm :

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

14 KiB Raw Permalink Blame History