Fala dataholics, mais uma dica rápida que pode te ajudar a incrementar as suas documentações, seja em notebooks ou nas suas páginas de Github.
Esse post é parte 2, pois, já tinha escrito esse post com algumas dicas de documentação.
Sabemos que documentação é extremamente importante, ela precisa ser clara e objetiva, sem muita enrolação, não é TCC por favor, mas de qualquer forma, tem pessoas que vivem disso e tem pessoas que gostam de caprichar bem nas suas documentações.
Nesse post mostrarei 2 dicas para enfeitar suas documentações, sim, enfeitar mesmo, deixar ela um pouquinho mais bonitinha rs, em alguns lugares chamado como "colocar flores" ou "perfumaria".
Mostrarei esses 2 tópicos:
Python ART
Badges com Shields.io
No último post falei sobre a DTSTOOLS, nela adicionei algumas artes, é claro que ficar bonito é subjetivo e o limite é a sua imaginação.
Existe uma biblioteca python que está publicada no PyPI chamada ART, podemos usá-la para gerar texto como desenho, isso é bem legal.
Com certeza, no passado alguém já gastou muito tempo fazendo esse desenho na mão, imagina o sofrimento rs.
Primeiro passo é instalar a biblioteca usando PIP.
Agora criaremos uma arte com a palavra Hello, essa fonte block cria um bloco em volta da palavra, mas, quando usamos o bloco não conseguimos controlar o tamanho da fonte.
Legal né? Imagina desenhar isso na mão? Algumas horinhas se tiver paciência.
Podemos gerar algumas artes aleatórias com tamanho da fonte pequena, se você rodar esse comando 10 vezes terá 10 artes diferentes.
Você pode também mudar o tamanho da fonte para médio ou grande.
O formato bolhas também é legal, mas nesse não da para definir o tamanho da fonte.
E aí curtiu essa primeira dica? Veja a documentação completa do Python ART:
A segunda dica é adicionar Badges no topo das suas documentações em Markdown, se você notar na maioria dos projetos do Github eles possuem alguns badges, exemplo esse do Spark.
Ele possui 4 badges para identificar algumas informações relevantes do projeto.
No projeto do DTSTOOLS adicionei alguns badges também.
HOMEPAGE - Link para o site do DataInAction
CONTRIBUTING - Um link para a página de contribuição do projeto no Github, esse é bastante legal quando você quer que outras pessoas contribuam no seu projeto
SLACK - Link do grupo de Databricks no Slack para tirar dúvidas
Github - O link do projeto no Github
Version - A versão atual da Build
Licença - Modelo de licença utilizado para redistribuição, o mais conhecido no mundo open source é o MIT
Plataforma - Indica onde você pode usar o código, esse badge criei, pois, ele não existia
E de onde vem esses Badges? Usei todos eles com base no https://shields.io/. Ele é um site dedicado para repositório e criação de novos Badges, é sensacional.
Para usar esses badges, você usará Markdown no seu notebook e fixaremos ele utilizando um pouco de HTML básico.
Esse é o resultado do código acima, note que todas as imagens apontam para o Shields.io
Adicionaremos um badge de versão, o legal desse badge de versão é que você vai trocando o número e a imagem vai mudando conforme o que você informar na URL.
Não se preocupe com o código ele esta no github e você pode copiar e colar.
Esse é o resultado do código acima.
Você pode criar seu próprio Badge no site do Shields.io basta colocar o nome e cor ele gera um badge customizado pra você.
Se você digitar qualquer palavra mais a cor desejada, você tem esse retorno.
Você pode fazer o teste pela API, simulando uma request GET na própria plataforma.
Posso também referenciar redes sociais, exemplo passando o ID do meu canal no Youtube:
Sensacional não é?! Explore todas as possibilidades, a documentação é bem completa e você pode customizar tudo que imagina.
Vale sempre ressaltar que deixar sua documentação com um visual legal é bacana, geralmente é bem chamativa para outros leitores, contudo essa é sempre a última coisa a se fazer na documentação, foque no importante que é a clareza e objetividade da documentação do projeto, depois vem a perfumaria.
Eai curtiu essas dicas?
Fiquem bem e até a próxima.
Referência:
Comments