
Algo que curto muito é ficar navegando na documentação de libs sinceramente uma documentação é algo que acho lindo de se ver e também difícil de manter 😅.
Imagine toda vez que seja feita alguma alteração em um comportamento de algo ir à página que explica fazer um copy paste do código, escrever o que ela faz agora, fazer o build, checar se está tudo certo, êpa não era pra ficar assim... eu já cansei só de imaginar 😤
Para facilitar isso existem algumas ferramentas como o MkDocs que facilitam bastante e nos ajudam a automatizar algumas tarefas chatas, nesse artigo vou escrever um pouco do que e como usei para fazer uma documentação de uma ferramenta Python, mas um ponto importante disso tudo é que MkDocs é agnóstico de linguagem então pode ser feito com outras linguagens também só dar uma olhadinha nadocumentação deles!
Ferramenta a ser documentada 🪲
Fiz uma ferramenta bem simples que realiza uma chamada na PokeAPI e pega informações relacionadas a um pokémon e mostra no terminal.
O código-fonte pode ser encontrado aqui:Documentação automática
Falando um pouco mais do projeto usei o poetry para gerenciar o ambiente virtual e deixar as libs que instalei isoladas do resto do sistema, ninguém quer ficar entulhando o pc com um monte de libs não é mesmo, mas você pode usar qualquer outra comopyenv,virtualenvwrapper é algo indiferente.
Bem as libs que instalei estão nopyproject.toml
e norequirements.txt
então é só instalar (umpip install -r requirements.txt deve funcionar) e começar a brincar.
Como documentar ✍️
Esse é um pedacinho do código que vou usar como exemplo para explicar para vocês, bem já deve ter reparado nessas"""
elas sãoDocstrings são usadas para documentar o código e é uma convenção bastante usada, para documentar módulos, classes, funções bem de qualquer forma se for documentar algo recomendo usar 😜 .
Essas docstrings que vão realizar a mágica vamos fazer com que elas sejam lidas de forma automática e inseridas na respectiva página de documentação do módulo. Bem com as docstrings inseridas e explicando o que cada função faz, vamos para prosseguir.
Instalando o MkDocs ⬆️
Para instalar usando oPoetry é bastante fácil basta usar umpoetry add oupip install caso não esteja o usando.
Bem instalamos omkdocs, um tema para deixar a documentação mais bonitamkdocs-material isso é questão de gosto no caso eu gosto muito, mas tem outros temas caso tenha interesse segue link com mais informaçõestemas de MkDocs. E por último temos omkdocstrings ele é um plugin que percorre nosso projeto e insere as docstrings encontradas dentro de nossas páginas.
Mas bem com as libs instaladas, o que fazemos agora? 🤔 não precisa mandar uma carta para o Caldeirão do Hulk é bem mais simples que isso 😂, seguindo o passo a passo logo você vai ter sua documentação pronta.
1 - Abra um terminal na pasta do projeto e use o comandomkdocs new .
, isso vai fazer com que os arquivos de configuração e a pastadocs sejam criadas.
2 - Neste momento você já deve ter um arquivo chamadomkdocs.yml
na raiz do seu projeto nele adicione as seguintes configurações.
site_name:Documentação Automática# Pode ser usado o nome da sua aplicaçãotheme:name:material# Adiciona o tema bonitinhoplugins:-search# Plugin que possibilita buscas pela documentação-mkdocstrings:# Esse que faz a mágica, mais informações abaixohandlers:python:setup_commands:-import sys-sys.path.append("src")watch:# Live-reload para os mais íntimos - mais informações abaixo também-src
Obs.: Sim, adicionei o código meio feio, mas assim você pode só copiar e colar, minha preguiça saúda a sua 👐
mkdocstrings: Como já comentei ele que lê as docstrings e adiciona na respectiva página que é relacionada com o módulo, mas já vamos ver como usar. De resto adicionei um código Python (sim ele aceita algumas funções python na configuração) para que a pasta
src
que é a que está o meu código seja reconhecido pela ferramenta, caso alguma pasta sua não seja reconhecida assim como a minha, esse é o caminho, basta adicionar ali e pronto.watch: Isso faz com que ao realizar uma alteração no código a mesma seja atualizada para que a documentação esteja sincronizada com o código tanto alterações no código quanto nas docstrings habilitam o reload da página, no caso adicionei a pasta onde está a minha aplicação, inclusive muito legal escrever a doc e já ver a mesma sendo inserida na página.
3 - Executemkdocs build
e depoismkdocs serve
e ele vai deixar a sua doc accessível pelo navegador pela urlhttp://127.0.0.1:8000/
. Você deve ter algo parecido com isso abaixo.
4 - Ao acessar você vai ter uma pequena introdução de como adicionar páginas, mas é muito simples basta criar um arquivo.md dentro da pastadocs que está na raiz do seu projeto e a mesma já é adicionada na estrutura da documentação. Se está tudo indo certo você vai ter uma estrutura parecida com essa abaixo, foco na pastadocs.
5 - Vamos atacar a página pokemon ela que vou usar para documentar o meu módulo pokemón que vimos no ínicio.
- Temos uma pequena introdução do que se trata aquela página e logo após vemos um
::: src.pokemon
mas do que se trata isso. Bem ele que mapeia o arquivo que será inserido de forma automática e partir dali é inserido a doc usando o caminho do arquivo (módulo se preferir) que está na pasta src é a mesma sintaxe do import, não acredita que funcionou? Olha o resultado aí em baixo!
6 - Aproveite 😁
Fim
Em alguns passos já temos uma doc bem legal e caso tenhamos mais um módulo ou seja necessário adicionar mais uma página é bem simples é só criar na pasta docs e está feito. Espero que tenha gostado e qualquer dúvida (ou se achou alguma coisa errada, acontece nas melhoras famílias) só mandar um comentário logo abaixo!
Top comments(0)
For further actions, you may consider blocking this person and/orreporting abuse