Doxygen: documentation on GitHub using gh-pages

In the last weeks I have been working on the project RiverNe3 commenting as much as possible because I was introducing many new programming concepts for me like Design Patterns and Java Concurrency.

Well, I chose Doxygen instead of Javadoc because it seems more complete and seems having more features…but anyhow, we can talk about in another post.

Once generated the documentation, I thought that anyone who wants to read the documentation doesn’t have to “build” its own documentation but the latter has to be always ready for who wants just take a look about what I did.

GitHub allows to have a web-page addressed to the repository in which it is hosts. So…why do not create only the html documentation and upload it as web site?

It’s pretty easy, because the idea behind is pretty easy: you just have to create a new branch named gh-pages and the most of the work is done.

The procedure I’m going to write has been taken from the very good guide written by richford on Put doxygen documentation on github using gh-pages.

In order to have a tidy repository on which you can go on working with different branches, the procedure is a bit tricky, but not very complicated.

Switch to the master branch in the main folder:

git checkout master

and add the path on which the documentation is going to be generated to the .gitignore file

echo "doc/html/" >> .gitignore

and then commit the modify on the master branch

git add .gitignore
git commit -m "Added html documentation folder to .gitignore"
git push origin master

Now, it’s time to go working on the repository of the documentation. First of all, move (create if not exist) into the directory of the documentation (in my case doc/html/) and clean it removing each and every file already created

cd doc/html/
rm -f *

Clone your own repository inside that folder, that will create a new directory with the name of the repository. In this way, you can easily manage the branch of the web-page of the documentation without touching the branches of the development of the source code.

git clone [email protected]:geoframecomponents/RiverNe3.git

Then copy everything in the folder created by the git clone command in the documentation directory (doc/html/ in my case) and remove the directory

cp -r ./RiverNe3/. ./
rm -r ./RiverNe3/

After having cloned the repo, create and switch the branch gh-pages with the single command:

git checkout -b gh-pages

That branch is automatically recognized by GitHub as Web Page, so uploading the Doxygen documentation in html format allows you to have your on-line documentation.

But we need to follow some other steps, before having the documentation available on-line.

Remove the master branch from within the folder of the documentation (the repository just cloned)

git branch -d master

and all the files and folders from the master branch, because cloning the remote repository you have just copied your repo inside a folder of your repo…is it clear? I hope so, not for me! 😀

Anyway you need to preserve only .git folder, for example

git rm -r src doc doxygen.conf LICENSE # and whatever else

and the commit the changes

git commit -m "Removed everything from gh-pages branch"

Now, come back to the main directory, and setup your doxygen.conf (if you don’t have already the doxygen.conf file, you can generate the default with doxygen -g doxygen.conf command) to generate the documentation in the right directory. Just edit it setting the path of the variable OUTPUT_DIRECTORY.

OUTPUT_DIRECTORY = ./doc/

So checkout the master branch and generate the Doxygen documentation

git checkout master
doxygen doxygen.conf

It’s time to push our documentation on the Word Wide Web!

Move into the documentation directory and checkout the gh-pages branch

cd doc/html/
git checkout gh-pages

Add each and every file generated by Doxygen

git add *.png
git add *.map
git add *.md5
git add *.html
git add *

commit and push the documentation!

git commit -m "Added all html documentation"
git push origin gh-pages

Now, your documentation is on-line on the web-site http://username.github.io/repoName/, in my case:

http://sidereus3.github.io/RiverNe3/

And now…the most import is keeping the documentation updated! A suggested workflow would look something like

# Do development stuff
git push origin master
doxygen doxygen.conf
cd doc/html
git add .
git commit -m "Updated documentation at Month day"
git push origin gh-pages

Enjoy!!! GWH!