Algo que curto muito ficar navegando na documentao de libs sinceramente uma documentao algo que acho lindo de se ver e tambm difcil de manter .

Imagine toda vez que seja feita alguma alterao em um comportamento de algo ir pgina que explica fazer um copy paste do cdigo, escrever o que ela faz agora, fazer o build, checar se est tudo certo, pa no 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 documentao de uma ferramenta Python, mas um ponto importante disso tudo que MkDocs agnstico de linguagem ento pode ser feito com outras linguagens tambm s dar uma olhadinha na documentao deles!

Ferramenta a ser documentada

Fiz uma ferramenta bem simples que realiza uma chamada na PokeAPI e pega informaes relacionadas a um pokmon e mostra no terminal.

O cdigo-fonte pode ser encontrado aqui: Documentao automtica

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, ningum quer ficar entulhando o pc com um monte de libs no mesmo, mas voc pode usar qualquer outra como pyenv, virtualenvwrapper algo indiferente.

Bem as libs que instalei esto no pyproject.toml e no requirements.txt ento s instalar (um pip install -r requirements.txt deve funcionar) e comear a brincar.

Como documentar

Esse um pedacinho do cdigo que vou usar como exemplo para explicar para vocs, bem j deve ter reparado nessas """ elas so Docstrings so usadas para documentar o cdigo e uma conveno bastante usada, para documentar mdulos, classes, funes bem de qualquer forma se for documentar algo recomendo usar .

Essas docstrings que vo realizar a mgica vamos fazer com que elas sejam lidas de forma automtica e inseridas na respectiva pgina de documentao do mdulo. Bem com as docstrings inseridas e explicando o que cada funo faz, vamos para prosseguir.

Instalando o MkDocs

Para instalar usando o Poetry bastante fcil basta usar um poetry add ou pip install caso no esteja o usando.

Bem instalamos o mkdocs, um tema para deixar a documentao mais bonita mkdocs-material isso questo de gosto no caso eu gosto muito, mas tem outros temas caso tenha interesse segue link com mais informaes temas de MkDocs. E por ltimo temos o mkdocstrings ele um plugin que percorre nosso projeto e insere as docstrings encontradas dentro de nossas pginas.

Mas bem com as libs instaladas, o que fazemos agora? no precisa mandar uma carta para o Caldeiro do Hulk bem mais simples que isso , seguindo o passo a passo logo voc vai ter sua documentao pronta.

1 - Abra um terminal na pasta do projeto e use o comando mkdocs new ., isso vai fazer com que os arquivos de configurao e a pasta docs sejam criadas.

2 - Neste momento voc j deve ter um arquivo chamado mkdocs.yml na raiz do seu projeto nele adicione as seguintes configuraes.

site_name: Documentao Automtica # Pode ser usado o nome da sua aplicaotheme:  name: material # Adiciona o tema bonitinhoplugins:- search # Plugin que possibilita buscas pela documentao- mkdocstrings: # Esse que faz a mgica, mais informaes abaixo    handlers:      python:        setup_commands:          - import sys          - sys.path.append("src")    watch: # Live-reload para os mais ntimos - mais informaes abaixo tambm      - src

Obs.: Sim, adicionei o cdigo meio feio, mas assim voc pode s copiar e colar, minha preguia sada a sua

• mkdocstrings: Como j comentei ele que l as docstrings e adiciona na respectiva pgina que relacionada com o mdulo, mas j vamos ver como usar. De resto adicionei um cdigo Python (sim ele aceita algumas funes python na configurao) para que a pasta src que a que est o meu cdigo seja reconhecido pela ferramenta, caso alguma pasta sua no seja reconhecida assim como a minha, esse o caminho, basta adicionar ali e pronto.

• watch: Isso faz com que ao realizar uma alterao no cdigo a mesma seja atualizada para que a documentao esteja sincronizada com o cdigo tanto alteraes no cdigo quanto nas docstrings habilitam o reload da pgina, no caso adicionei a pasta onde est a minha aplicao, inclusive muito legal escrever a doc e j ver a mesma sendo inserida na pgina.

3 - Execute mkdocs build e depois mkdocs serve e ele vai deixar a sua doc accessvel pelo navegador pela url http://127.0.0.1:8000/. Voc deve ter algo parecido com isso abaixo.

4 - Ao acessar voc vai ter uma pequena introduo de como adicionar pginas, mas muito simples basta criar um arquivo .md dentro da pasta docs que est na raiz do seu projeto e a mesma j adicionada na estrutura da documentao. Se est tudo indo certo voc vai ter uma estrutura parecida com essa abaixo, foco na pasta docs.

5 - Vamos atacar a pgina pokemon ela que vou usar para documentar o meu mdulo pokemn que vimos no nicio.

• Temos uma pequena introduo do que se trata aquela pgina e logo aps vemos um ::: src.pokemon mas do que se trata isso. Bem ele que mapeia o arquivo que ser inserido de forma automtica e partir dali inserido a doc usando o caminho do arquivo (mdulo se preferir) que est na pasta src a mesma sintaxe do import, no 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 mdulo ou seja necessrio adicionar mais uma pgina bem simples s criar na pasta docs e est feito. Espero que tenha gostado e qualquer dvida (ou se achou alguma coisa errada, acontece nas melhoras famlias) s mandar um comentrio logo abaixo!