From 77c1988a8b826aeb02be362a7a88391315bbf606 Mon Sep 17 00:00:00 2001 From: Fabio Serrao Date: Fri, 2 Jul 2021 10:42:29 -0300 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Add=20Portuguese=20translation?= =?UTF-8?q?=20for=20Development=20Contributing=20(#1364)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/pt/docs/contributing.md | 511 +++++++++++++++++++++++++++++++++++ 1 file changed, 511 insertions(+) create mode 100644 docs/pt/docs/contributing.md diff --git a/docs/pt/docs/contributing.md b/docs/pt/docs/contributing.md new file mode 100644 index 000000000..327b8b607 --- /dev/null +++ b/docs/pt/docs/contributing.md @@ -0,0 +1,511 @@ +# Desenvolvimento - Contribuindo + +Primeiramente, você deveria ver os meios básicos para [ajudar FastAPI e pedir ajuda](help-fastapi.md){.internal-link target=_blank}. + +## Desenvolvendo + +Se você já clonou o repositório e precisa mergulhar no código, aqui estão algumas orientações para configurar seu ambiente. + +### Ambiente virtual com `venv` + +Você pode criar um ambiente virtual em um diretório utilizando o módulo `venv` do Python: + +
+ +```console +$ python -m venv env +``` + +
+ +Isso criará o diretório `./env/` com os binários Python e então você será capaz de instalar pacotes nesse ambiente isolado. + +### Ativar o ambiente + +Ative o novo ambiente com: + +=== "Linux, macOS" + +
+ + ```console + $ source ./env/bin/activate + ``` + +
+ +=== "Windows PowerShell" + +
+ + ```console + $ .\env\Scripts\Activate.ps1 + ``` + +
+ +=== "Windows Bash" + + Ou se você usa Bash para Windows (por exemplo Git Bash): + +
+ + ```console + $ source ./env/Scripts/activate + ``` + +
+ +Para verificar se funcionou, use: + +=== "Linux, macOS, Windows Bash" + +
+ + ```console + $ which pip + + some/directory/fastapi/env/bin/pip + ``` + +
+ +=== "Windows PowerShell" + +
+ + ```console + $ Get-Command pip + + some/directory/fastapi/env/bin/pip + ``` + +
+ +Se ele exibir o binário `pip` em `env/bin/pip` então funcionou. 🎉 + + + +!!! tip + Toda vez que você instalar um novo pacote com `pip` nesse ambiente, ative o ambiente novamente. + + Isso garante que se você usar um programa instalado por aquele pacote (como `flit`), você utilizará aquele de seu ambiente local e não outro que possa estar instalado globalmente. + +### Flit + +**FastAPI** utiliza Flit para construir, empacotar e publicar o projeto. + +Após ativar o ambiente como descrito acima, instale o `flit`: + +
+ +```console +$ pip install flit + +---> 100% +``` + +
+ +Ative novamente o ambiente para ter certeza que você esteja utilizando o `flit` que você acabou de instalar (e não um global). + +E agora use `flit` para instalar as dependências de desenvolvimento: + +=== "Linux, macOS" + +
+ + ```console + $ flit install --deps develop --symlink + + ---> 100% + ``` + +
+ +=== "Windows" + + Se você está no Windows, use `--pth-file` ao invés de `--symlink`: + +
+ + ```console + $ flit install --deps develop --pth-file + + ---> 100% + ``` + +
+ +Isso irá instalar todas as dependências e seu FastAPI local em seu ambiente local. + +#### Usando seu FastAPI local + +Se você cria um arquivo Python que importa e usa FastAPI, e roda com Python de seu ambiente local, ele irá utilizar o código fonte de seu FastAPI local. + +E se você atualizar o código fonte do FastAPI local, como ele é instalado com `--symlink` (ou `--pth-file` no Windows), quando você rodar aquele arquivo Python novamente, ele irá utilizar a nova versão do FastAPI que você acabou de editar. + +Desse modo, você não tem que "instalar" sua versão local para ser capaz de testar cada mudança. + +### Formato + +Tem um arquivo que você pode rodar que irá formatar e limpar todo o seu código: + +
+ +```console +$ bash scripts/format.sh +``` + +
+ +Ele irá organizar também todos os seus imports. + +Para que ele organize os imports corretamente, você precisa ter o FastAPI instalado localmente em seu ambiente, com o comando na seção acima usando `--symlink` (ou `--pth-file` no Windows). + +### Formato dos imports + +Tem outro _script_ que formata todos os imports e garante que você não tenha imports não utilizados: + +
+ +```console +$ bash scripts/format-imports.sh +``` + +
+ +Como ele roda um comando após o outro, modificando e revertendo muitos arquivos, ele demora um pouco para concluir, então pode ser um pouco mais fácil utilizar `scripts/format.sh` frequentemente e `scripts/format-imports.sh` somente após "commitar uma branch". + +## Documentação + +Primeiro, tenha certeza de configurar seu ambiente como descrito acima, isso irá instalar todas as requisições. + +A documentação usa MkDocs. + +E existem ferramentas/_scripts_ extras para controlar as traduções em `./scripts/docs.py`. + +!!! tip + Você não precisa ver o código em `./scripts/docs.py`, você apenas o utiliza na linha de comando. + +Toda a documentação está no formato Markdown no diretório `./docs/pt/`. + +Muitos dos tutoriais tem blocos de código. + +Na maioria dos casos, esse blocos de código são aplicações completas que podem ser rodadas do jeito que estão apresentados. + +De fato, esses blocos de código não estão escritos dentro do Markdown, eles são arquivos Python dentro do diretório `./docs_src/`. + +E esses arquivos Python são incluídos/injetados na documentação quando se gera o site. + +### Testes para Documentação + +A maioria dos testes na verdade rodam encima dos arquivos fonte na documentação. + +Isso ajuda a garantir: + +* Que a documentação esteja atualizada. +* Que os exemplos da documentação possam ser rodadas do jeito que estão apresentadas. +* A maior parte dos recursos é coberta pela documentação, garantida por cobertura de testes. + +Durante o desenvolvimento local, existe um _script_ que constrói o site e procura por quaisquer mudanças, carregando na hora: + +
+ +```console +$ python ./scripts/docs.py live + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +Isso irá servir a documentação em `http://127.0.0.1:8008`. + +Desse jeito, você poderá editar a documentação/arquivos fonte e ver as mudanças na hora. + +#### Typer CLI (opcional) + +As instruções aqui mostram como utilizar _scripts_ em `./scripts/docs.py` com o programa `python` diretamente. + +Mas você pode usar também Typer CLI, e você terá auto-completação para comandos no seu terminal após instalar o _completion_. + +Se você instalou Typer CLI, você pode instalar _completion_ com: + +
+ +```console +$ typer --install-completion + +zsh completion installed in /home/user/.bashrc. +Completion will take effect once you restart the terminal. +``` + +
+ +### Aplicações e documentação ao mesmo tempo + +Se você rodar os exemplos com, por exemplo: + +
+ +```console +$ uvicorn tutorial001:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +como Uvicorn utiliza por padrão a porta `8000`, a documentação na porta `8008` não dará conflito. + +### Traduções + +Ajuda com traduções É MUITO apreciada! E essa tarefa não pode ser concluída sem a ajuda da comunidade. 🌎 🚀 + +Aqui estão os passos para ajudar com as traduções. + +#### Dicas e orientações + +* Verifique sempre os _pull requests_ existentes para a sua linguagem e faça revisões das alterações e aprove elas. + +!!! tip + Você pode adicionar comentários com sugestões de alterações para _pull requests_ existentes. + + Verifique as documentações sobre adicionar revisão ao _pull request_ para aprovação ou solicitação de alterações. + +* Verifique em _issues_ para ver se existe alguém coordenando traduções para a sua linguagem. + +* Adicione um único _pull request_ por página traduzida. Isso tornará muito mais fácil a revisão para as outras pessoas. + +Para as linguagens que eu não falo, vou esperar por várias pessoas revisarem a tradução antes de _mergear_. + +* Você pode verificar também se há traduções para sua linguagem e adicionar revisão para elas, isso irá me ajudar a saber que a tradução está correta e eu possa _mergear_. + +* Utilize os mesmos exemplos Python e somente traduza o texto na documentação. Você não tem que alterar nada no código para que funcione. + +* Utilize as mesmas imagens, nomes de arquivo e links. Você não tem que alterar nada disso para que funcione. + +* Para verificar o código de duas letras para a linguagem que você quer traduzir, você pode usar a Lista de códigos ISO 639-1. + +#### Linguagem existente + +Vamos dizer que você queira traduzir uma página para uma linguagem que já tenha traduções para algumas páginas, como o Espanhol. + +No caso do Espanhol, o código de duas letras é `es`. Então, o diretório para traduções em Espanhol está localizada em `docs/es/`. + +!!! tip + A principal ("oficial") linguagem é o Inglês, localizado em `docs/en/`. + +Agora rode o _servidor ao vivo_ para as documentações em Espanhol: + +
+ +```console +// Use o comando "live" e passe o código da linguagem como um argumento de linha de comando +$ python ./scripts/docs.py live es + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +Agora você pode ir em http://127.0.0.1:8008 e ver suas mudanças ao vivo. + +Se você procurar no site da documentação do FastAPI, você verá que toda linguagem tem todas as páginas. Mas algumas páginas não estão traduzidas e tem notificação sobre a falta da tradução. + +Mas quando você rodar localmente como descrito acima, você somente verá as páginas que já estão traduzidas. + +Agora vamos dizer que você queira adicionar uma tradução para a seção [Recursos](features.md){.internal-link target=_blank}. + +* Copie o arquivo em: + +``` +docs/en/docs/features.md +``` + +* Cole ele exatamente no mesmo local mas para a linguagem que você quer traduzir, por exemplo: + +``` +docs/es/docs/features.md +``` + +!!! tip + Observe que a única mudança na rota é o código da linguagem, de `en` para `es`. + +* Agora abra o arquivo de configuração MkDocs para Inglês em: + +``` +docs/en/docs/mkdocs.yml +``` + +* Procure o lugar onde `docs/features.md` está localizado no arquivo de configuração. Algum lugar como: + +```YAML hl_lines="8" +site_name: FastAPI +# Mais coisas +nav: +- FastAPI: index.md +- Languages: + - en: / + - es: /es/ +- features.md +``` + +* Abra o arquivo de configuração MkDocs para a linguagem que você está editando, por exemplo: + +``` +docs/es/docs/mkdocs.yml +``` + +* Adicione no mesmo local que está no arquivo em Inglês, por exemplo: + +```YAML hl_lines="8" +site_name: FastAPI +# Mais coisas +nav: +- FastAPI: index.md +- Languages: + - en: / + - es: /es/ +- features.md +``` + +Tenha certeza que se existem outras entradas, a nova entrada com sua tradução esteja exatamente na mesma ordem como na versão em Inglês. + +Se você for no seu navegador verá que agora a documentação mostra sua nova seção. 🎉 + +Agora você poderá traduzir tudo e ver como está toda vez que salva o arquivo. + +#### Nova linguagem + +Vamos dizer que você queira adicionar traduções para uma linguagem que ainda não foi traduzida, nem sequer uma página. + +Vamos dizer que você queira adicionar tradução para Haitiano, e ainda não tenha na documentação. + +Verificando o link acima, o código para "Haitiano" é `ht`. + +O próximo passo é rodar o _script_ para gerar um novo diretório de tradução: + +
+ +```console +// Use o comando new-lang, passe o código da linguagem como um argumento de linha de comando +$ python ./scripts/docs.py new-lang ht + +Successfully initialized: docs/ht +Updating ht +Updating en +``` + +
+ +Agora você pode verificar em seu editor de código o mais novo diretório criado `docs/ht/`. + +!!! tip + Crie um primeiro _pull request_ com apenas isso, para iniciar a configuração da nova linguagem, antes de adicionar traduções. + + Desse modo outros poderão ajudar com outras páginas enquanto você trabalha na primeira. 🚀 + +Inicie traduzindo a página principal, `docs/ht/index.md`. + +Então você pode continuar com as instruções anteriores, para uma "Linguagem Existente". + +##### Nova linguagem não suportada + +Se quando rodar o _script_ do _servidor ao vivo_ você pega um erro sobre linguagem não suportada, alguma coisa como: + +``` + raise TemplateNotFound(template) +jinja2.exceptions.TemplateNotFound: partials/language/xx.html +``` + +Isso significa que o tema não suporta essa linguagem (nesse caso, com um código falso de duas letras `xx`). + +Mas não se preocupe, você pode configurar o tema de linguagem para Inglês e então traduzir o conteúdo da documentação. + +Se você precisar fazer isso, edite o `mkdocs.yml` para sua nova linguagem, teremos algo como: + +```YAML hl_lines="5" +site_name: FastAPI +# Mais coisas +theme: + # Mais coisas + language: xx +``` + +Altere essa linguagem de `xx` (do seu código de linguagem) para `en`. + +Então você poderá iniciar novamente o _servidor ao vivo_. + +#### Pré-visualize o resultado + +Quando você usa o _script_ em `./scripts/docs.py` com o comando `live` ele somente exibe os arquivos e traduções disponíveis para a linguagem atual. + +Mas uma vez que você tenha concluído, você poderá testar tudo como se parecesse _online_. + +Para fazer isso, primeiro construa toda a documentação: + +
+ +```console +// Use o comando "build-all", isso leverá um tempinho +$ python ./scripts/docs.py build-all + +Updating es +Updating en +Building docs for: en +Building docs for: es +Successfully built docs for: es +Copying en index.md to README.md +``` + +
+ +Isso gera toda a documentação em `./docs_build/` para cada linguagem. Isso inclui a adição de quaisquer arquivos com tradução faltando, com uma nota dizendo que "esse arquivo ainda não tem tradução". Mas você não tem que fazer nada com esse diretório. + +Então ele constrói todos aqueles _sites_ independentes MkDocs para cada linguagem, combina eles, e gera a saída final em `./site/`. + +Então você poderá "servir" eles com o comando `serve`: + +
+ +```console +// Use o comando "serve" após rodar "build-all" +$ python ./scripts/docs.py serve + +Warning: this is a very simple server. For development, use mkdocs serve instead. +This is here only to preview a site with translations already built. +Make sure you run the build-all command first. +Serving at: http://127.0.0.1:8008 +``` + +
+ +## Testes + +Tem um _script_ que você pode rodar 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` no seu navegador, poderá explorar interativamente as regiões de código que estão cobertas pelos testes, e observar se existe alguma região faltando. + +### Testes no seu editor + +Se você quer usar os testes integrados em seu editor adicione `./docs_src` na sua variável `PYTHONPATH`. + +Por exemplo, no VS Code você pode criar um arquivo `.env` com: + +```env +PYTHONPATH=./docs_src +```