Fabio Serrao
4 years ago
committed by
GitHub
GitHub
1 changed files with 511 additions and 0 deletions
@ -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