Desenvolvimento

1 fev, 2017

MkDocs – Documentação de projetos com Markdown

Publicidade

Fala pessoal, tudo certo?

O artigo de hoje é sobre uma ferramenta que descobri algum tempo atrás e que achei bacana compartilhar. Vamos estudar a criação de um site para a documentação de nossos projetos utilizando a ferramenta MkDocs.

O MkDocs é um gerador de site estático minimalista e muito simples de usar. Ele funciona de maneira semelhante a outros geradores como Pelican e Jenkill, entretanto, diferente desses, o MkDocs é voltado à criação de documentação ao invés de blogs.

Os sites contruídos com o MkDocs podem ser hospedados facilmente em muitos lugares, inclusive utilizando o github pages.

Instalação

O MKDocs possui suporte para as versões 2.6, 2.7, 3.3, 3.4, 3.5 do Python. A sua instalação é semelhante a outros pacotes Python.

pip install mkdocs

Podemos utilizar o seguinte comando para verificar se tudo foi instalado corretamente:

mkdocs --version

Se tudo estiver funcionado corretamente, o resultado do comando será a versão do MkDocs instalado.

Criando o projeto

A utilização do MkDocs é bem simples. Inicialmente criamos o nosso projeto com:

mkdocs new my-project
cd my-project

Dentro da pasta my-projet teremos a seguinte estrutura de diretórios:

.
├── docs
│   └── index.md
└── mkdocs.yml

Todas as páginas do seu site serão armazenadas dentro da pasta docs. Inclusive dentro dessa mesma pasta existe o arquivo index.md. Este arquivo será a página principal do site. Além do diretório docs, também temos o arquivo mkdocs.yml, que é o arquivo de configuração utilizado pelo MkDocs.

Servidor de desenvolvimento

O MkDocs possui um servidor de desenvolvimento, que nos permite pré-visualizar nossa documentação. Para utilizar entre com o comando:

mkdocs serve

Veremos algo semelhante em nosso terminal:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 170125 15:05:33 server:283] Serving on http://127.0.0.1:8000
[I 170125 15:05:33 handlers:60] Start watching changes
[I 170125 15:05:33 handlers:62] Start detecting changes

Um ponto interessante deste servidor de desenvolvimento é que ele atualiza automaticamente o conteúdo exibido na página sem necessidade de reiniciá-lo. Sendo necessário apenas atualizar a página do navegador. Uma vez que o servidor esteja sendo executado, podemos acessar o site de documentação no navegador pelo seguinte endereço: http://localhost:8000/ ou http://127.0.0.1:8000

Adicionado novas paginas

A página da imagem acima é o conteúdo do index.md. Podemos adicionar outra página facilmente editando a tag pages presente no arquivo mkdocs.yml.

site_name: My Docs
pages:
    - Home: index.md
    - About: about.md

Em seguida, criamos um arquivo about.md dentro da pasta docs e atualizamos a página no navegador para que o menu aparecera no topo do site, nos permitindo navegar entre as páginas.

Outras configurações

Para trocarmos o nome do site, basta alterarmos o nome presente na tag site_name. Também podemos trocar o tema do site através da tag theme. O MkDocs vem com alguns temas próprios, que são os temas mkdocs (utilizado neste tutorial) e o readthedocs (utilizado muito em documentação de api Python). Também existem temas feitos por terceiros, que podem ser encontrados aqui. Para utilizá-los siga as instruções de instalação de cada tema.

Compilando

Quando o site de documentação estiver pronto, o próximo passo é compilá-lo. Isso é feito através do comando:

mkdocs build

Um diretório chamato site será criado.

about
css
fonts
img
js
mkdocs
404.html
index.html
sitemap.xml

O conteúdo deste diretório é o nosso site em si, pronto para ser hospedado no github-pages (o seu conteúdo pode ser lançado na branch gh-pages) ou em outro servidor, de acordo com a preferência.

O MkDocs possui um comando onde ele compila o site e já o envia para o github-pages. Para mais informações, dê uma olhada na documentação (em inglês) aqui.

Conclusão

Chegamos ao fim de mais um artigo. Este foi bem curto, apenas para apresentar o mkdocs. Futuramente, pretendo fazer outro explicando como realizar o deploy no github-pages e, inclusive, como automatizar esse processo.

Eu recentemente utilizei o MkDocs no site/documentação do meu leitor de quadrinhos Pynocchio aqui.

É isso, pessoal! Obrigado por ler até aqui.

Até o próximo artigo!

Referências