Documentando projetos com o Daux.io

Duax.io é uma solução bem simples e prática que auxília na criação de documentação para projetos web. Essa semana traduzi um artigo para o Tuts+ sobre a ferramenta e fiz alguns testes. Neste post vou mostrar como é simples configurar e criar um documentação com Daux.io.


Além do fato de uma documentação ser praticamente um item indispensável em um projeto de sistema, seja para web ou não, ela também aumenta e muito a confiabilidade de uma solução, pois quem optar utilizar a mesma tem algum recurso de suporte. Nunca deixe a documentação de um projeto de lado.

O que é o Daux.io?

O Daux.io é uma solução bem simples criada para auxiliar na produção da documentações de projetos de sistemas. A documentação é composta por arquivos Markdown, que sobrepostos em ordem numérica nas pastas do projeto, criam a documentação.

Documentando projetos web com o Daux.io by Web Social Dev

Quem já utilizou soluções como Jekyll, Ghost, Gravit ou até mesmo o GitHub pages, vai entender o mecanismo aqui. Primeiro é criado um template, que no caso do Daux.io é baseado no Bootstrap, e em cima deste são geradas as páginas, que são padronizadas. O conteúdo das páginas é gerado com base nos arquivos Markdown no diretório da documentação, que são ordenados por números.

Existem duas maneiras de utilizar o Daux.io. A primeira é utilizar um servidor local WAMP ou similar dependendo do sistema operacional, e executar a documentação com PHP. A outra, caso você queira fazer testes locais, é utilizar o Grunt.

Neste artigo vamos utilizar o serviço Cloud9 para criar o ambiente de desenvolvimento.

Configurando o ambiente

Se você ainda não conhece o Cloud9, tem algum tempo que escrevi um artigo sobre ele, depois de testar e perceber que ele é mais simples e útil que o Codio (minha atual IDE online até então).

Basicamente, você só precisa de uma conta no GitHub para acessar o Cloud9. Feito isso, vamos começar a partir dashboard do usuário, como na imagem abaixo.

Documentando projetos web com o Daux.io by Web Social Dev

Crie um novo Workspace. No meu caso eu foi criado um com o nome testando_daux. Para o servidor, vamos utilizar o ambiente PHP, conforme a imagem.

Documentando projetos web com o Daux.io by Web Social Dev

Feito isso, nosso ambiente está criado, agora vamos configura-lo. Para confirmar se o NPM está instalado, basta no terminal, executar o comando npm -v. O resultado deve ser similar ao da imagem abaixo.

Documentando projetos web com o Daux.io by Web Social Dev

Com o NPM devidamente instalado, podemos passar a configuração do Daux.io. Acesse página do Daux.io e clique na opção download. Você será direcionado a página de download do GitHub, onde se encontra o repositório da solução. Provavelmente você vai baixar um arquivo com o nome daux.io-master.zip.


Configurando o Daux.io

Envie o arquivo baixado para o ambiente do Cloud9 (isso pode ser feito até mesmo com a função drag and drop) e descompacte o arquivo. Uma dica, renomeie a pasta que foi descompactada para um nome mais simples, como doc ou documentacao. Por enquanto, nosso ambiente segue conforme a imagem abaixo.

Documentando projetos web com o Daux.io by Web Social Dev

Note que na pasta doc, que é resultado do arquivo compactado que baixamos do Daux.io, já contém arquivos padrões para criação de páginas para web.

Na pasta Docs, estão todos os documentos que compõem a documentação. Note que os arquivos na pasta são agrupados utilizando um números em ordem crescente, com extensão .md, que é a extensão para arquivos Markdown. A propósito, se você precisa de auxílio para entender a sintaxe de arquivos de texto Markdown, esse manual do GitHub pode ajudar.

Documentando projetos web com o Daux.io by Web Social Dev

Além dos arquivos que compõem a documentação, na pasta Docs também temos um arquivo super importante chamado config.json, responsável pela configuração e principais informações da documentação, como título, descrição, autor, entre outros. Nele você pode incluir as informações suas informações junto as informações da documentação. Fiz uma graça com o meu:

Documentando projetos web com o Daux.io by Web Social Dev

O resultado, ao carregar a página da documentação, foi a alteração do título, da descrição e da imagem, que mudei para a mesma, mas com o link da página online, apenas para não quebrar a formatação da página. Segue exemplo.

Documentando projetos web com o Daux.io by Web Social Dev

Para alterar o tema padrão, por exemplo, altere a linha theme para um dos parâmetros:

  • daux-blue
  • daux-green
  • daux-navy
  • daux-red

Você pode conferir mais configurações deste arquivo na documentação do Daux.io.


Conclusão

Para quem precisa de uma solução simples e eficaz para documentação de projetos web, o Daux.io pode ser uma solução e tanto, apesar de existir diversas outras na web. Quem quiser dar uma olhada no meu exemplo, por enquanto ele está acessível no link https://testanto-daux-thierryrene.c9.io/doc.

Fiz esse post para complementar o post que traduzi para o Tuts+, sobre o Daux.io.

  • Quem quiser testar o demo, me da um toque, às vezes a stack do c9 hiberna, ai eu reativo.