Documentar um sistema e uma tarefa que muitos desenvolvedores consideram árdua por ser demorada, mas se tivesse alguma forma de criar toda documentação do nosso sistema somente com uma simples configuração, não seria legal? Pesquisando sobre essa tema em projetos desenvolvidos com .ts encontrei o compodoc.

Compodoc é um gerador de documentação desenvolvido para projetos .ts, para utilizar ele nós somente precisamos configurar o seu pacote para ler o nosso arquivo tsconfig.app.json. Vejamos nesse artigo como configurar ele para gerar a documentação baseada projeto em um projeto Angular com TypeScript.

Configuração inicial

Para esse artigo irei clonar um projeto criado para o artigo: Angular Autenticação com Firebase.

O primeiro passo será baixar o compodoc para o projeto. Para isso, execute o seguinte comando no seu terminal:

npm install <a href="http://twitter.com/compodoc/compodoc">@compodoc/compodoc</a> --save-dev

Com o pacote no seu projeto, atualize o seu arquivo package.json com o seguinte trecho de código:

"generate-docs": "compodoc -p src/tsconfig.app.json",
"serve-docs": "compodoc -s src/tsconfig.app.json"
},

Note que eu adicionei o caminho do arquivo tsconfig.app.json com base no meu projeto, caso o seu esteja configurando em outro path, você precisa alterar aqui para o compodoc funcionar corretamente.

Gerando a documentação

O próximo passo será gerar a documentação do projeto. Para isso execute o seguinte comandos no seu terminal:

npm run generate-docs

A execução do comando a cima irá criar um novo diretório chamado documentation dentro da solução do seu projeto. Podemos ver o resultado desse passo na imagem abaixo:

Com esse passo você já pode subir a sua documentação em um servidor e passar o link para outros integrantes da sua equipe, mas para finalizar esse artigo eu irei demonstrar como executar ela em um servidor local.

Para isso, execute o seguinte comando abaixo no seu terminal e abra no seu navegador o endereço que ele irá apresentar na sua console.

npm run serve-docs 

Documentação

O Compodoc cria uma documentação completa do projeto, com ele nos temos registrado desde a estrutura do projeto contendo quantidade de arquivo para modules, components … etc até um link ver mais detalhes de cada um desses itens. Podemos ver na imagem abaixo um print da tela com a documentação que ele criou com base no projeto que utilizamos para esse artigo.

Caso tenha interesse em comhecer um pouco mais o compodoc, segue link do seu projeto no GitHub Compodoc.