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