Skip to content

Documentação Doxygen

Jump to bottom
Renato Coutinho edited this page Jun 2, 2016 · 14 revisions

O Doxygen usa comentários padronizados no código para gerar um hipertexto de documentação. A documentação Doxygen de nosso projeto está no branch gh-pages. Para cada projeto o GitHub permite criar um brach destes para abrigar um site (detalhes aqui e página resultante aqui).

A cada vez que o código ou comentários sofrem mudanças que afetem a documentação é preciso atualizar o branch gh-pages. Abaixo instruções para fazer isso chamando manualmente o Doxygen e enviando o resultado para o branch gh-pages (adaptado de http://rickfoosusa.blogspot.com.br/2011/10/howto-use-doxygen-with-github.html):

1. Preparação dos diretórios (basta uma vez)

  • No seu computador, vá para o diretório da cópia e trabalho de seu fork do projeto. Cerifique-se de que está no branch master digitando:

git checkout master

  • Crie um diretório chamado html no branch master
  • Certifique-se que há no branch master um arquivo .gitignore que tenha uma linha

html/

  • Certifique-se de que no branch master há o arquivo de configuração Doxyfile, com os parâmetros

OUTPUT_DIRECTORY = doc

HTML_OUTPUT = html

  • Mude para o diretório html que você criou. Dentro dele crie uma nova cópia do seu fork do projeto

git clone [email protected]:YOUR-GITHUB-USERNAME/TWoLife.git -b gh-pages --single-branch .

Preste atenção ao ponto no final do comando. A sua pasta html/ agora deve conter vários arquivos html, png js etc., não apenas uma subpasta TWoLife.

  • Pronto! Agora temos um diretório html para receber os arquivos gerados pelo Doxygen e enviá-los ao branch gh-pages no GitHub. Não edite nada neste diretório, o Doxygen fará o serviço.

2. Configuração automática da atualização da documentação

Crie um arquivo dentro do diretório principal (não o html), em .git/hooks/post-commit com o seguinte conteúdo:

#!/bin/bash
# post-commit hook que automaticamente compila a documentação e, se não houver
# erros, dá commit e push no gh-pages
set -e

[[ "$(git symbolic-ref --short HEAD)" == "master" ]] || exit 0

last_rev="$(git rev-parse HEAD)"

doxygen Doxyfile

if [ $? == 0 ]; then
    cd html/
    git add .
    git commit -m "Updating doxygen docs for rev ${last_rev}"
    git push origin gh-pages
fi

A seguir, torne este arquivo executável rodando chmod +x .git/hooks/post-commit. Pronto! A cada commit o git vai automaticamente gerar a nova documentação e atualizá-la!

3. Alternativamente: atualização manual da documentação Doxyfile

  • Quando terminar o trabalho nos arquivos do branch master , execute o Doxygen. Isto vai atualizar a documentação no diretório html, criado e configurado conforme o passo 1, acima.

  • Em seu diretório local, mude para o diretório html, Verifique que você está no branch gh-pages e se houve mudanças nos arquivos com

git checkout gh-pages

  • Em caso positivo, adicione as mudanças e faça o commit

git add *

git commit -m "atualizacao dos docs de Doxygen"

  • Por fim, ainda neste diretório e branch, envie as mudanças para sua cópia do fork no GitHub

git push origin gh-pages

Clone this wiki locally