Código de documentação é um processo pelo qual um programador documenta o código. É um termo bem conhecido entre os engenheiros. Se eles não fizerem isso, isso leva a uma má legibilidade do código e manutenção difícil para outros membros da equipe.
Code documentation is different from project documentation as it aims mainly at how the system work but these two processes have something in common – requirements of using a professional tool. Neste artigo, eu resumo algumas ferramentas populares para criar documentação de código.
LaTex
LaTeX é um sistema de preparação de documentos para composição tipográfica de alta qualidade. É mais frequentemente usado para documentos técnicos ou científicos de médio a grande porte mas pode ser usado para quase todas as formas de publicação.
LaTeX não é um processador de texto! Em vez disso, LaTeX incentiva os autores a não se preocuparem muito com a aparência de seus documentos, mas a se concentrarem em obter o conteúdo certo.
LaTeX é um sistema de composição tipográfica de alta qualidade; ele inclui recursos projetados para a produção de documentação técnica e científica. LaTeX é o padrão de facto para a comunicação e publicação de documentos científicos. LaTeX está disponível como software livre.
Você não precisa pagar pelo uso do LaTeX, ou seja não há taxas de licença, etc.
Pandoc
Pandoc compreende uma série de extensões úteis de sintaxe de markdown, incluindo metadados de documentos (título, autor, data); notas de rodapé; tabelas; listas de definição; sobrescrito e subscrito; strikeout; listas ordenadas melhoradas (número inicial e estilo de numeração são significativos); listas de exemplos em execução; blocos de código delimitados com destaque de sintaxe; aspas inteligentes, traços e elipses; markdown dentro de blocos HTML; e LaTeX em linha. Se a compatibilidade de markdown for desejada, todas essas extensões podem ser desligadas.
Existem muitas maneiras de personalizar o Pandoc para atender às suas necessidades, incluindo um sistema de modelos e um poderoso sistema para escrever filtros.
Pandoc inclui uma biblioteca Haskell e um programa autônomo de linha de comando. A biblioteca inclui módulos separados para cada formato de entrada e saída, portanto adicionar um novo formato de entrada ou saída só requer adicionar um novo módulo.
Pandoc é software livre, lançado sob a GPL.
Markdown
Markdown é uma ferramenta de conversão de texto para HTML para web writers. Markdown permite que você escreva usando um formato de texto simples e fácil de ler, e depois converta-o para XHTML (ou HTML) estruturalmente válido.
O objetivo principal do design da sintaxe de formatação do Markdown é torná-lo o mais legível possível. A ideia é que um documento em formato Markdown deve poder ser publicado tal como está, como texto simples, sem parecer que foi marcado com tags ou instruções de formatação. Embora a sintaxe do Markdown tenha sido influenciada por vários filtros de texto para HTML existentes, a maior fonte de inspiração para a sintaxe do Markdown é o formato de e-mail em texto simples.
LiveEdu
LiveEdu permite que você transmita sua documentação de código e crie “Documentação de código em vídeo”
Ecosistema de Educação é um ecossistema de aprendizado descentralizado que ensina profissionais e estudantes universitários a construir produtos reais. Você pode descrever o nosso produto como um híbrido de Pluralsight e Twitch. Estamos construindo o maior ecossistema de aprendizado do mundo para tópicos de tecnologia futura, como inteligência artificial, segurança cibernética, desenvolvimento de jogos, ciência de dados, moedas criptográficas e programação. Ecosistema Educacional é baseado em vídeo e cada projeto contém vídeos, um esboço de projeto estruturado, repo de projeto, e recursos para download. Os usuários podem clonar recursos de projetos do Ecosistema Educacional Git e rodar os aplicativos em sua máquina local.
Sphinx
Sphinx é uma ferramenta que facilita a criação de documentação inteligente e bonita, escrita por Georg Brandl e licenciada sob a licença BSD.
Foi originalmente criada para a documentação Python, e tem excelentes facilidades para a documentação de projetos de software em uma variedade de linguagens. Aqui estão alguns recursos:
- Formatos de saída: HTML (incluindo ajuda HTML do Windows), LaTeX (para versões PDF imprimíveis), ePub, Texinfo, páginas de manual, texto simples.
- Referências cruzadas extensivas: marcação semântica e links automáticos para funções, classes, citações, termos de glossário e informações similares.
- Estrutura hierárquica: fácil definição de uma árvore de documentos, com links automáticos para irmãos, pais e filhos.