13 KiB

Raw Permalink Blame History

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

# 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

# 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

# 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

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

# 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

Inicie o Jupyter na raiz do repositório: jupyter notebook
Navegue até a pasta da lição desejada
Abra os ficheiros .ipynb para realizar os exercícios
Os notebooks são autossuficientes, com explicações e células de código
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

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

# 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

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

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

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:

Crie um recurso Azure Static Web App
Conecte ao repositório GitHub
Configure as definições de construção:
- Localização da aplicação: quiz-app
- Localização de saída: dist
O fluxo de trabalho do GitHub Actions fará a implantação automática ao fazer push

Site de Documentação

# 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

# 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

Desenvolvimento Local: Instale Python, Jupyter, Node.js localmente
GitHub Codespaces: Ambiente de desenvolvimento instantâneo na nuvem
Contêineres de Desenvolvimento do VS Code: Desenvolvimento local baseado em contêineres
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:

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

Falhas na Instalação do npm:

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

13 KiB Raw Permalink Blame History