diff --git a/docs/pt/docs/contributing.md b/docs/pt/docs/contributing.md new file mode 100644 index 000000000..6c523fef5 --- /dev/null +++ b/docs/pt/docs/contributing.md @@ -0,0 +1,399 @@ +# Desenvolvimento - Contribuindo + +Primeiro, você poderá querer ver as formas básicas de [ajudar o FastAPI e obter ajuda](help-fast-api.md){.internal-link target=_blank}. + +## Desenvolvimento + +Se você já clonou o repositório fastapi e quer mergulhar fundo no código, aqui estão algumas orientações para configurar o seu ambiente. + +### Ambiente virtual + +Siga as instruções para criar e ativar um [ambiente virtual](virtual-environments.md){.internal-link target=_blank} para o código interno do `fastapi`. + +### Instalar requisitos usando o pip + +Depois de ativar o ambiente, instale os pacotes necessários: + +
+ +```console +$ pip install -r requirements.txt + +---> 100% +``` + +
+ +Isso vai instalar todas as dependências e seu FastAPI local no seu ambiente local. + +### Usando seu FastAPI local + +Se criou um arquivo Python que importe e use o FastAPI, e o executa com o Python em seu ambiente local, ele irá usar o código fonte do seu FastAPI local clonado. + +E se atualizar o código fonte local do FastAPI quando voltar a executar o arquivo Python, ele utilizará a nova versão do FastAPI que acabou de editar. + +Desta forma, você não tem que "instalar" sua versão local para poder testar todas as alterações. + +/// note | Detalhe técnicos + +Isso só acontece quando você instala usando o `requirements.txt` ao invés de executar `pip install fastapi` diretamente. + +Isso acontece porque dentro do arquivo `requirements.txt`, a versão local do FastAPI está marcada para ser instalada em modo "editável", com a opção `-e`. + +/// + +### Formatar o código + +Existe um script que você pode executar para formatar e limpar todo o seu código: + +
+ +```console +$ bash scripts/format.sh +``` + +
+ +Também classifica automaticamente todas as suas importações. + +## Testes + +Existe um script que pode ser executado localmente para testar todo o código e gerar relatórios de cobertura em HTML: + +
+ +```console +$ bash scripts/test-cov-html.sh +``` + +
+ +Esse comando gera um diretório `./htmlcov/`, se você abrir o arquivo `./htmlcov/index.html` em seu navegador, você pode explorar interativamente as regiões de código que são cobertas pelos testes, e avisam se falta alguma região. + +## Documentação + +Primeiro, certifique-se de configurar seu ambiente como descrito acima, que instalará todos os requisitos. + +### Documentação em tempo real + +Durante o desenvolvimento local, existe um script que constrói o site e verifica se existem alterações, ou seja, live-reloading: + +
+ +```console +$ python ./scripts/docs.py live + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +A documentação será mostrada em `http://127.0.0.1:8008`. + +Desse modo, você pode editar os arquivos da documentação/fonte e ver as alterações em tempo real. + +/// tip | Dica + +Alternativamente, você pode executar os mesmos passos que os scripts fazem manualmente. + +Vá para a pasta do idioma, para os documentos principais em inglês, estão em `docs/en`: + +```console +$ cd docs/en/ +``` + +Então execute `mkdocs` nesse diretório: + +```console +$ mkdocs serve --dev-addr 127.0.0.1:8008 +``` + +/// + +#### Typer CLI (opcional) + +As instruções aqui mostram como usar o script `./scripts/docs.py` com o programa `python` diretamente. + +Mas você também pode usar o Typer CLI, e obterá o preenchimento automático dos comandos no seu terminal após a instalação completa. + +Se instalar o Typer CLI, você pode instalar o completion com: + +
+ +```console +$ typer --install-completion + +zsh completion installed in /home/user/.bashrc. +Completion will take effect once you restart the terminal. +``` + +
+ +### Estrutura dos documentos + +A documentação usa o MkDocs. + +E existem ferramentas/scripts adicionais para lidar com traduções em `./scripts/docs.py`. + +/// tip | Dica + +Não é preciso ver o código em `./scripts/docs.py`, basta usá-lo na linha de comando. + +/// + + +Toda a documentação está no formato Markdown no diretório `./docs/en/` + +Muitos dos tutoriais têm blocos de código. + +Na maioria dos casos, estes blocos de código são verdadeiras aplicações completas que podem ser executadas como estão. + +Na verdade, esses blocos de código não estão escritos dentro do Markdown, eles são arquivos Python no diretório `./docs_src/`. + +E esses arquivos Python são incluídos/injetados na documentação quando gera o site. + +### Documentos para testes + +A maioria dos testes é executada com base nos arquivos de exemplo da documentação. + +Isso ajuda a garantir que: + +* A documentação está atualizada. +* Os exemplos da documentação podem ser executados como estão. +* A maioria das funcionalidades são cobertas pela documentação, garantidas pelo teste de cobertura. + +#### Aplicações e documentação ao mesmo tempo + +Se executar os exemplos com, por exemplo: + +
+ +```console +$ fastapi dev tutorial001.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +como o Uvicorn por padrão usa a porta `8000`, a documentação na porta `8008` não vai colidir. + +### Traduções + +A ajuda com as traduções é MUITO apreciada! E isso não pode ser feito sem a ajuda da comunidade. 🌎🚀 + +Aqui estão os passos para ajudar com as traduções + +#### Dicas e orientações + +* Verifique os pull requests existentes para o seu idioma. Por exemplo, para Espanhol, a label é `lang-es`. + +* Revise esses pull requests, solicitando modificações ou aprovando eles. Para os idiomas que não falo, espero que outras pessoas revisem a tradução antes do merging. + +/// tip | Dica + +É possível adicionar comentários com sugestões de alteração para pull requests existentes. + +Verifique os documentos sobre como adicionar uma revisão de pull request para aprová-la ou solicitar alterações. + +/// + +* Verifique se existe uma GitHub Discussion para coordenar traduções para o seu idioma. Pode subscrevê-lo, e quando houver um novo pull request para revisão, um comentário automático será adicionado à discussão. + +* Se traduzir páginas, adicione um único pull request por página traduzida. Isso fará com que seja muito mais fácil para os outros revisarem. + +* Para revisar o código de 2-letras do idioma que quer traduzir, pode usar a tabela Lista de códigos ISO 639-1. + +#### Idiomas existentes + +Digamos que quer traduzir uma página para um idioma que já tem traduções para algumas páginas, como Espanhol. + +Nesse caso do Espanhol, o código de 2-letras é `es`. Então, o diretório para as traduções em espanhol está localizado em `docs/es/`. + +/// tip | Dica + +O idioma principal (oficial) é o Inglês, localizado em `docs/en`. + +/// + +Agora, execute o live server para os documentoes em Espanhol. + +
+ +```console +// Use o comando "live" e passe o código do idioma como argumento CLI +$ python ./scripts/docs.py live es + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +/// tip | Dica + +Como alternativa, você pode executar os mesmos passos que os scripts fazem manualmente. + +Vá para o diretório do idioma, para traduções em Espanhol está em `docs/es`: + +```console +$ cd docs/es/ +``` + +Em seguida, execute `mkdocs` nesse diretório: +Then run `mkdocs` in that directory: + +```console +$ mkdocs serve --dev-addr 127.0.0.1:8008 +``` + +/// + +Agora vá para http://127.0.0.1:8008 e veja suas alterações em tempo real. + +Você verá que todos os idiomas têm todas as páginas. Mas algumas páginas não estão traduzidas e têm uma caixa de informação no topo, sobre a tradução em falta. + +Agora, digamos que você quer adicionar uma tradução para a seção [Features](features.md){.internal-link target=_blank}. + +* Copie o arquivo em: + +``` +docs/en/docs/features.md +``` + +* Cole-o exatamente no mesmo local mas para o idioma que pretende traduzir, por exemplo: + +``` +docs/es/docs/features.md +``` + +/// tip | Dica + +Note que a única alteração no caminho e o nome do arquivo é o código do idioma, de `en` para `es`. + + +/// + +Se for ao seu navegador verá que agora os documentos mostram a sua nova seção (a caixa de informação no topo desapareceu). 🎉 + +Agora pode traduzir tudo e ver como fica quando salvar o arquivo. + + +#### Não traduza essas páginas + +🚨 Não traduza: + +* Arquivos em `reference/` +* `release-notes.md` +* `fastapi-people.md` +* `external-links.md` +* `newsletter.md` +* `management-tasks.md` +* `management.md` +* `contributing.md` + +Alguns desses arquivos são atualizados com muita frequência e uma tradução estaria sempre atrasada, ou incluem o conteúdo principal dos arquivos fonte do Inglês, etc. + +#### Novo Idioma + +Digamos que quer adicionar traduções para um idioma que ainda não está traduzida, nem mesmo algumas páginas. + +E quer adicioanr traduções para Creole, e ele ainda não está em docs. + +Verificando o link abaixo, o código para "Creole" é `ht`. + +O próximo passo é executar o script para gerar um novo diretório de tradução: + +
+ +```console +// Use o comando new-lang, passe o código do idioma como argumento CLI +$ python ./scripts/docs.py new-lang ht + +Successfully initialized: docs/ht +``` + +
+ +Agora pode verificar em seu editor de código o novo diretório criado `docs/ht/`. + +Esse comando criou um arquivo `docs/ht/mkdocs.yml` com uma configuração simples que herda tudo da versão `en`: + +```yaml +INHERIT: ../en/mkdocs.yml +``` + +/// tip | Dica + +Você também pode simplesmente criar esse arquivo com esse conteúdos manualmente. + +/// + +Esse comando também criou um arquivo fictício `docs/ht/index.md` para a página principal, pode começar por traduzir este. + +Pode continuar com as intruções anteriores para uma "Idioma Existente" para esse processo. + +Você pode fazer o primeiro pull request com esses dois arquivos, `docs/ht/mkdocs.yml` e `docs/ht/index.md`. 🎉 + + +#### Pré-visualizar o resultado + +Como já mencionado acima, pode-se usar o `./scripts/docs.py` com o comando `live` para pré-visualizar os resultados (or `mkdocs serve`) + +Uma vez pronto, pode também testar tudo como ficaria online, incluindo todos os outros idiomas. + +Para fazer isso, comece por construir todos os documentos: + +
+ +```console +// Use o comando "build-all", isto vai demorar um pouco +$ python ./scripts/docs.py build-all + +Building docs for: en +Building docs for: es +Successfully built docs for: es +``` + +
+ +Isso constrói todos os sites MkDocs para cada idioma, combina-os, e gera o resultado final em `./site/`. + +Depois, pode servi-lo com o comando `serve`: + +
+ +```console +// Use o comando "serve" depois de executar "build-all" +$ python ./scripts/docs.py serve + +Aviso: esse é um um servidor muito simples. Para desenvolvimento, use o mkdocs em vez disso. +Isso está aqui apenas para pré-visualizar um site com traduções já construídas. +Certifique-se de executar o comando build-all primeiro. +Servindo em: http://127.0.0.1:8008 + +``` + +
+ +#### Sugestões e orientações específicas para a tradução + +* Traduza apenas os documentos Markdown (`.md`). Não traduza exemplos de código em `./docs_src`. + +* Em blocos de código dentro do documento Markdown, traduza os comentários (`# um comentário`), mas deixe o resto inalterado. + +* Não altere nada do que está incluído em "``" (código em linha). + +* Nas linhas que começam com `///` traduza apenas a parte do text depois de `|`. Deixe o resto inalterado. + +* Pode traduzir caixas de informação como `/// warning` como por exemplo `/// warning | Achtung`. Mas não altere a palavra imediatamente após o `///`, pois isso determina a cor da caixa de informação. + +* Não altere os caminhos nos links para imagens, arquivos de código, documentos Markdown. + +* No entanto, quando um documento Markdown é traduzido os `#hash-parts` em links para os cabeçalhos pode mudar. Atualize esses links se possível. + * Procure por esses links no documento traduzido usando o regex `#[^# ]`. + * Procure em todos os documentos já traduzidos para o seu idioma por `your-translated-document.md`. Por exemplo VS Code tem uma opção "Editar" -> "Procurar em Arquivos". + * Ao traduzir um documento, não "pré-traduza" `#hash-parts` que ligam a títulos em documentos não traduzidos.