Imagine a seguinte situação: você, caro desenvolvedor da cobrinha, criou um projeto que pela empolgação ou pela paixão ao código assumiu uma proporção ligeiramente maior que o esperado (sendo carinhoso na descrição do tamanho). Você já é uma pessoa inteligente então você já sabe que precisa documentar o projeto pois sabe que esquecer os detalhes é uma facilidade grande da sua profissão; eis então o desafio: como raios fazer para documentar de forma padronizada um projeto Python?

Esbarrando exatamente nessa questão eu resolvi procurar soluções e, talvez pela minha exigência - de repente fortalecida pela minha vontade de criar algo - resolvi fazer minha própria ferramenta, algo que pudesse ler toda a codebase do meu projeto, gerar uma documentação consistente do código e disponibilizar o resultado final de uma forma ainda editável para ajustes finos. Inspirado pelo mágico cargo doc do Rust eu lhes apresento o Mosheh

Documentação oficial: https://lucasgoncsilva.github.io/mosheh/

Sabe aqueles problemas de projeto mal documentado e descrito? Eles NÃO existem aqui: tudo o que a ferramenta realiza e como utilizar cada nuance está bem descrito. Essa é uma questão que me preocupei bastante pois sei o quanto é deprimente procurar informações simples que não estão onde deveriam estar. Ainda assim, como diz o ditado: "life is not a strawberry".

Desafios

Dentre os impressionantes desafios que encontrei na criação desse meliante eu gostaria de listar três deles:

1. Consistência de Tipos: Graças ao Python e sua tipagem dinâmica e duvidosa - quase inexistente - que não valida nativamente os tipos de dados, criar um mecanismo onde os tipos são consistentes demandou certo tempo de planejamento e algumas tentativas...
2. Criação de Logs: Admito estar ainda inseguro quanto à implementação do sistema de logs por dois motivos, sendo o primeiro o fato de haver um logger.debug(...) a cada duas linhas e o segundo o fato da execução verbosa multiplicar consideravelmente a execução do script.
3. Implementação de Testes Automatizados: Eles já me salvaram de enviar problemas para o PyPI, mas parece que vez ou outra eu é que preciso ser salvo deles; não há um problema grave quanto ao modo de implementação, mas parte dos testes são literalmente as próprias funções testadas fazendo testes nelas mesmas...

Próximos Passos

O Mosheh está bem longe de se tornar uma ferramenta perfeita, há muito trabalho a ser feito, como verificar prossíveis problemas de execução em Windows (não pude validar até o momento) ou providenciar uma lógica de "exclude", altamente necessária e recomendada, ou ainda um parâmetro que traduza a saída entre EN (padrão) ou PT-BR, mas certamente ele está seguindo o caminho correto.

Sinta-se livre para analisar, avaliar, dar um feedback e contribuir caso lhe apeteça, sua contribuição terá muito valor, nem que seja para fazer uso real da ferramenta, eu assumo o risco...