mirror of https://github.com/tiangolo/fastapi.git
🌐 Add Portuguese translation for Development Contributing (#1364)
This commit is contained in:
Fabio Serrao
GitHub
parent
26a36f79fa
commit
77c1988a8b
|
|
@ -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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ python -m venv env
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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"
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ source ./env/bin/activate
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
=== "Windows PowerShell"
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ .\env\Scripts\Activate.ps1
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
=== "Windows Bash"
|
||||
|
||||
Ou se você usa Bash para Windows (por exemplo <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ source ./env/Scripts/activate
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
Para verificar se funcionou, use:
|
||||
|
||||
=== "Linux, macOS, Windows Bash"
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ which pip
|
||||
|
||||
some/directory/fastapi/env/bin/pip
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
=== "Windows PowerShell"
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ Get-Command pip
|
||||
|
||||
some/directory/fastapi/env/bin/pip
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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 <a href="https://flit.readthedocs.io/en/latest/index.html" class="external-link" target="_blank">Flit</a> para construir, empacotar e publicar o projeto.
|
||||
|
||||
Após ativar o ambiente como descrito acima, instale o `flit`:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ pip install flit
|
||||
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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"
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ flit install --deps develop --symlink
|
||||
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
=== "Windows"
|
||||
|
||||
Se você está no Windows, use `--pth-file` ao invés de `--symlink`:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ flit install --deps develop --pth-file
|
||||
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ bash scripts/format.sh
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ bash scripts/format-imports.sh
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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 <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
|
||||
|
||||
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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ python ./scripts/docs.py live
|
||||
|
||||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
|
||||
<span style="color: green;">[INFO]</span> Start watching changes
|
||||
<span style="color: green;">[INFO]</span> Start detecting changes
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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 <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, 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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ typer --install-completion
|
||||
|
||||
zsh completion installed in /home/user/.bashrc.
|
||||
Completion will take effect once you restart the terminal.
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Aplicações e documentação ao mesmo tempo
|
||||
|
||||
Se você rodar os exemplos com, por exemplo:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uvicorn tutorial001:app --reload
|
||||
|
||||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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 <a href="https://github.com/tiangolo/fastapi/pulls" class="external-link" target="_blank">_pull requests_ existentes</a> para a sua linguagem e faça revisões das alterações e aprove elas.
|
||||
|
||||
!!! tip
|
||||
Você pode <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">adicionar comentários com sugestões de alterações</a> para _pull requests_ existentes.
|
||||
|
||||
Verifique as documentações sobre <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">adicionar revisão ao _pull request_</a> para aprovação ou solicitação de alterações.
|
||||
|
||||
* Verifique em <a href="https://github.com/tiangolo/fastapi/issues" class="external-link" target="_blank">_issues_</a> 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 <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">Lista de códigos ISO 639-1</a>.
|
||||
|
||||
#### 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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```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
|
||||
|
||||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
|
||||
<span style="color: green;">[INFO]</span> Start watching changes
|
||||
<span style="color: green;">[INFO]</span> Start detecting changes
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
Agora você pode ir em <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> 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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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`:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
## Testes
|
||||
|
||||
Tem um _script_ que você pode rodar localmente para testar todo o código e gerar relatórios de cobertura em HTML:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ bash scripts/test-cov-html.sh
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
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
|
||||
```
|
||||
Loading…
Reference in New Issue