# AGENTS.md ## Visão Geral do Projeto Data Science for Beginners é um currículo abrangente de 10 semanas e 20 lições criado pelos Advocates de Nuvem da Microsoft Azure. O repositório é um recurso de aprendizado que ensina conceitos fundamentais de ciência de dados por meio de lições baseadas em projetos, incluindo notebooks Jupyter, quizzes interativos e tarefas práticas. **Principais Tecnologias:** - **Jupyter Notebooks**: Meio principal de aprendizado usando Python 3 - **Bibliotecas Python**: pandas, numpy, matplotlib para análise e visualização de dados - **Vue.js 2**: Aplicativo de quiz (pasta quiz-app) - **Docsify**: Gerador de site de documentação para acesso offline - **Node.js/npm**: Gerenciamento 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-na-Prática) - Cada lição inclui README, notebooks, tarefas e quizzes - Aplicativo de quiz 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 ```bash # 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 ```bash # 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 do Aplicativo de Quiz ```bash # 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 ```bash # 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): ```bash # 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 1. Inicie o Jupyter na raiz do repositório: `jupyter notebook` 2. Navegue até a pasta da lição desejada 3. Abra os arquivos `.ipynb` para realizar os exercícios 4. Os notebooks são autossuficientes, com explicações e células de código 5. 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 no 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 do Aplicativo de Quiz - Aplicativo Vue.js 2 com recarregamento automático durante o desenvolvimento - Quizzes armazenados em `quiz-app/src/assets/translations/` - Cada idioma tem sua própria pasta de tradução (en, fr, es, etc.) - A numeração dos quizzes começa em 0 e vai até 39 (40 quizzes no total) ### Adicionando Traduções - Traduções vão na pasta `translations/` na raiz do repositório - Cada idioma tem a estrutura completa das lições espelhada do inglês - Tradução automatizada via GitHub Actions (co-op-translator.yml) ## Instruções de Teste ### Teste do Aplicativo de Quiz ```bash 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 arquivos de dados estão acessíveis e os resultados são gerados corretamente - Certifique-se de que as visualizações são renderizadas corretamente ### Teste de Documentação ```bash # 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 ```bash # 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 sendo 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: ```python 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 Vue de arquivo único (.vue files) - Mantenha uma arquitetura baseada em componentes - Execute `npm run lint` antes de enviar alterações ### Documentação Markdown - Use uma hierarquia clara de cabeçalhos (# ## ### etc.) - Inclua blocos de código com especificadores de linguagem - Adicione texto alternativo para imagens - Link para lições e recursos relacionados - Mantenha os comprimentos das linhas razoáveis para facilitar a leitura ### Organização de Arquivos - Conteúdo das lições em pastas numeradas (01-defining-data-science, etc.) - Soluções em subpastas dedicadas `solution/` - Traduções espelham a estrutura em inglês na pasta `translations/` - Mantenha os arquivos de dados na pasta `data/` ou em pastas específicas de lições ## Construção e Implantação ### Implantação do Aplicativo de Quiz ```bash 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 O quiz-app pode ser implantado no Azure Static Web Apps: 1. Crie um recurso Azure Static Web App 2. Conecte ao repositório GitHub 3. Configure as configurações de build: - Localização do aplicativo: `quiz-app` - Localização de saída: `dist` 4. O workflow do GitHub Actions fará a implantação automática ao enviar alterações ### Site de Documentação ```bash # 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 - 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 Enviar ```bash # 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` - `[Aplicativo de Quiz] Adicionar tradução em alemão` - `[Docs] Atualizar README com novos pré-requisitos` ### Verificações Necessárias - Certifique-se de que todo o código funciona sem erros - Verifique se os notebooks executam completamente - Confirme que os aplicativos Vue.js são construídos com sucesso - Verifique se os links da documentação funcionam - Teste o aplicativo de quiz se modificado - 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 - Revise o arquivo CONTRIBUTING.md ## Notas Adicionais ### Bibliotecas Comuns Utilizadas - **pandas**: Manipulação e análise de dados - **numpy**: Computação numérica - **matplotlib**: Visualização e plotagem de dados - **seaborn**: Visualização estatística de dados (algumas lições) - **scikit-learn**: Aprendizado de máquina (lições avançadas) ### Trabalhando com Arquivos de Dados - Arquivos de dados localizados na pasta `data/` ou em diretórios específicos de lições - A maioria dos notebooks espera arquivos de dados em caminhos relativos - Arquivos 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 - Workflow de tradução em `.github/workflows/co-op-translator.yml` - Traduções na pasta `translations/` com códigos de idioma - Traduções de quizzes em `quiz-app/src/assets/translations/` ### Opções de Ambiente de Desenvolvimento 1. **Desenvolvimento Local**: Instale Python, Jupyter, Node.js localmente 2. **GitHub Codespaces**: Ambiente de desenvolvimento instantâneo baseado em nuvem 3. **Contêineres de Desenvolvimento do VS Code**: Desenvolvimento local baseado em contêiner 4. **Binder**: Inicie notebooks na nuvem (se configurado) ### Diretrizes de Conteúdo das Lições - Cada lição é independente, mas constrói conceitos anteriores - Quizzes pré-lição testam conhecimento prévio - Quizzes pós-lição reforçam o aprendizado - Tarefas fornecem prática prática - Sketchnotes fornecem resumos visuais ### Solução de Problemas Comuns **Problemas com Kernel do Jupyter:** ```bash # Ensure correct kernel is installed python -m ipykernel install --user --name=datascience ``` **Falhas na Instalação do npm:** ```bash # 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 - Confira a compatibilidade da versão do Python (recomendado Python 3.7+) - Certifique-se de que o ambiente virtual está ativado **Docsify Não Carregando:** - Verifique se você está servindo a partir da raiz do repositório - Confira se o arquivo `index.html` existe - Certifique-se de que há acesso adequado à rede (porta 3000) ### Considerações de Desempenho - Conjuntos de dados grandes podem levar tempo para 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 rápida - Builds de produção são otimizados e minificados ### Notas de Segurança - Nenhum dado sensível ou credenciais deve ser enviado - 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 patches de segurança ## Contribuindo com Traduções - Traduções automatizadas gerenciadas via GitHub Actions - Correções manuais são bem-vindas para precisão das traduções - Siga a estrutura de pastas de tradução existente - Atualize os links dos quizzes 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](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.