Autodoc Yaml

coverage coverage 96% 96%

O Autodoc Yaml foi criado com intuito de facilitar o processo de documentação de software, onde o usuário apenas necessita seguir um padrão de comentários com algumas anotações (labels) utilizando a sintaxe de arquivosyaml para que a documentação seja gerada de forma automatica, é uma ferramenta de linha de comando que funciona com projetos construídos em python, java, yaml, javascript e typescript.

Extensão de snippets para Vscode

Juntamente com o Autodoc Yaml foi desenvolvida uma extensão para o Vscode possuindo snippets (atalhos) para acelerar/facilitar o processo de escrita da documentação, basta fazer o download no link abaixo e usufruir dos atalhos.

Autodoc Yaml Snippets

Instalação

Para realizar a instalação do pacote é necessário ter o versão 8.+ do node.js, caso já possua o mesmo instalado em sua máquina, executar o seguinte comando:

npm i -g autodoc_yaml

após finalizar o download do pacote, abrir os arquivos que devem ser documentados e comentar as classes e métodos seguindo o seguinte padrão:

/// - annotation: 
///     title: comandosBasicos
///     text_description:
///	   - Método construtor da classe.
///     parameters:
///	   - WebDriver: driver
///     ex:
///     - language: java
/// 	   - WebDriver driver = new WebDriver();
///	   - ComandosBasicos comBasico = new ComandosBasicos(driver);
///     return: void

Os blocos de documentação devem conter no inicio de cada linha a 3 barras (///) caso a linguagem utilizada tenha o padrão de comentário usando barra, caso contrátio utilizar 3 cerquilhas (###), que é o simbolo usado para comentários em outras linguagens como python.Além disso é possível também gerar a documentação fazendo as anotações direto em arquivos yaml, na pasta yamlFIles.

Obs: se for necessário utilizar o simbolo de dois pontos ( : ) ou 2 asteriscos ( ** ) no texto, o mesmo deve ficar entre aspas duplas para que seja tratado de forma literal.A label Annotation deve conter a seguinte estrutura ( - Annotation), pois cada uma representa um bloco diferente de documentação,além disso apenas é o único label que é obrigatório os demais podem ser incluidos de acordo com a necessidade e caso seja necessário usar mais de uma anotação num mesmo bloco, será preciso separar os labels repetidas por uma label annotation o nome do mesmo incluindo um número no finalizar como no exemplo abaixo:

/// - annotation: 
///     title: comandosBasicos
///     text_description:
///	    - Método construtor da classe.
///     parameters:
///	    - WebDriver: driver
/// - annotation: 
///     text_description:
///	    - segunda anotação de text_description.
///     ex:
/// 	    - WebDriver driver = new WebDriver();
///	    - ComandosBasicos comBasico = new ComandosBasicos(driver);
///     return: void

Descrição das labels de um bloco de documentação

Annotation

Label obrigatória em todo o bloco de documentação, ela serve para delimitar o inicio de um novo bloco, e a mesma deve a seguinte estrutura:

/// - annotation: 
///    demais label...

logo

Label que acrescenta um logo nas páginas, tem a seguinte sintaxe:

/// - annotation: 
///     logo: caminhoDoLogo.extensão

mainTitle

Label que cria um título principal no bloco, tem a seguinte sintaxe:

/// - annotation: 
///     mainTitle: comando exemplo mainTitle

title

Label que cria um título principal secundário no bloco, tem a seguinte sintaxe:

/// - annotation: 
///     title: comando exemplo title

text_description

Label que cria um paragrafo no bloco, no inicio de cada linha de cada linha deve ser inserida com o caractere traço ( - ) no inicio e incluir as labels paragraph para definir os paragrafos como o exemplo abaixo:

/// - annotation: 
///     text_description:
///     - paragraph:
///	       - primeira linha do paragrafo.
///	       - segunda linha do paragrafo.
///	       - terceira linha do paragrafo.
///     - paragraph:
///	       - primeira linha do paragrafo.
///	       - segunda linha do paragrafo.
///	       - terceira linha do paragrafo.

parameters

Label que cria um ou mais parêmetros para auxiliar na descrição de um método ou função, cada parâmetro deve ser inserido em uma linha com o caractere traço ( - ) no inicio como o exemplo abaixo:

/// - annotation: 
///     parameters:
///	    - tipoDoParametro: nomeDoParametro
///	    - tipoDoParametro2: nomeDoParametro2

ex

Label que cria um bloco de exemplo de código para auxiliar na descrição de um método ou função, no inicio de cada linha deve ser inserido com o caractere traço ( - ) seguido do nome da linguagem e dois pontos ( : ) no inicio como o exemplo abaixo:

/// - annotation: 
///     ex:
/// 	    - language: nome da linguagem;
///	    - linha de script;
///	    - linha de script;
///	    - linha de script;

exception

Label que cria um bloco de paragrafo de descrição de uma exception como o exemplo abaixo:

/// - annotation: 
///     exception: descrição da excepetion

return

Label que cria a descrição do retorno de um método ou função como o exemplo abaixo:

/// - annotation: 
///     return:
///        - tipoRetorno: descrição do retorno
///        - tipoRetorno: descrição do retorno

image

Label que cria uma imagem deve receber o altText que será o título da imagem e o texto de acessibilidade caso o link da imagem esteja quebrado e o nome da mesma junto com a extensão como o exemplo abaixo:

/// - annotation: 
///     image:
///     - imageLink: avatar.png
///     - altText: DevOps Logo

unorderedList

Label que cria uma lista inordenada cada item deve ser inserido em uma linha com o caractere traço ( - ) no inicio como o exemplo abaixo:

/// - annotation: 
///     unorderedList:
///        - item 1
///        - item 2
///        - item 3

orderedList

Label que cria uma lista ordenada cada item deve ser inserido em uma linha com o caractere traço ( - ) no inicio como o exemplo abaixo:

/// - annotation: 
///     orderedList:
///        - item 1
///        - item 2
///        - item 3

link

Label que cria uma lista ordenada cada item deve ser inserido em uma linha com o caractere traço ( - ) no inicio como o exemplo abaixo:

/// - annotation: 
///     link:
///        - linkText: link do google
///        - linkUrl: http://google.com

logo

Label que insere um logo no topo e no rodapé dos pdf's gerados, é necessário que o logo esteja na raiz do projeto e essa anotação deve ir no inicio da documentação (na anotação que fica no inicio do pdf) e deve ser implementada da seguinte forma:

/// - annotation: 
///     logo:

Exemplo de uso em um arquivo java

/// - annotation: 
///     mainTitle: exemplo
///     text_description:
///         - paragraph:
///	           - Classe de exemplo.
public class exemplo {
/// - annotation: 
///     title: exemplo
///     text_description:
///         - paragraph:
///	            - Método de teste
///     parameters:
///	       - String: teste
///     ex:
///         - language: java
///         - exemplo('texto');
///     return:
///	     - void: método não tem retorno
   public void exemplo(String teste) {
	    this.teste = teste;
   }
}

Exemplo de uso em um arquivo python

### - annotation: 
###     mainTitle: exemplo
###     text_description:
###	       - paragraph:
###	           - Classe de exemplo.
class exemplo(object):
### - annotation: 
###     title: exemplo
###     text_description:
###	       - paragraph:
###	           - Método de teste
###     parameters:
###	       - string: teste
###     ex:
///         - language: python
### 	       - exemplo('texto')
###     return: método não tem retorno
     def exemplo(teste):
 	    self.teste = teste

Command Line (CLI)

No final depois de finalizar o processo de documentação, basta executar os comandos com os devidos parâmetros na raiz do projeto documentado para que a documentação seja gerada.

Options: -V, --version output the version number -h, --help output usage information

Commands:

• cucumber [options] gera o cucumber report
  • -t --theme [value] tema do html. ["bootstrap", "hierarchy", "foundation", "simple"] default: hierarchy.
  • -g --ignorefiles [value] caminho dos arquivos que serão ignorados. [optional]
  • -i --inputpath [value] caminho para o json do cucumber. [required]
  • -o --outputpath [value] caminho de saída da documentação. [required]
  • -h, --help informação de uso
• gherkin [options] gera a documentação a partir do guerkin
  • -f --format [value] formato de exportação da documentação. ["pdf", "html", "all"] default: pdf.
  • -n --name [value] nome do arquivo que será exportado.
  • -i --inputpath [value] caminho para os aqruivos .feature. [required]
  • -o --outputpath [value] caminho da saída do documento. [required]
  • -h, --help informação de uso
• doc [options] gera a documentação automatica.
  • -l --language [value] linguagem dos arquivos documentados
  • -o --outputPath [value] caminho de sáida da documentação (default a raiz de onde foi executado o comando) . [optional]
  • -h, --help informação de uso

As opções de linguagem disponíveis são as seguintes:

1. javascript
2. typescript
3. java
4. python
5. yaml O processo será iniciado e documentação será gerada coso toda as estruturaesteja correta é só acessar a pasta documentation e visualizar os arquivos gerados

Observações finais

A lib irá criar na raiz do projeto uma pasta documentation contendo as seguintes pastas:

• confluenceFiles
• images
• yamlFiles
• jsonFiles
• mdFiles
• pdfFiles os arquivos de documentação gerados serão armazenados nas pastas citadas anteriormente, além disso os arquivos md podem ser visualizados através de um algum software de preview no no vscode, basta instalar um plugin, ou, então abrir os pdf's exportados na documentação na pasta pdfFiles.

PS: os arquivos exportados na pasta confluenceFiles são gerados no padrão do confluence, e podem ser usados para publicação da documentação sem a necessidade de adaptação.