Put doxygen documentation on github using gh-pages

[richford]

TLDR: Someone with admin privileges will have to complete the steps below in order to put our doxygen documentation online using gh-pages

At the last MADNESS meeting we talked about setting up the doxygen documentation on a gh-pages branch. This is a little more complicated than manually writing our own index.html and pushing it to the gh-pages branch. The problem is summarized below (from here)

The problem with this setup – and using doxygen – is that gh-pages will be an empty branch on first commit, and only hold static web pages thereafter. Checking out gh-pages stashes your source code away meaning you can no longer run doxygen against it. The trick is to actually clone your project into a subdirectory, add that directory to gh-pages and push those changes up to origin. Then in the clone subdirectory, you checkout gh-pages and use that folder just for the gh-pages branch. Your project folder can continue to be used as normal while doxygen can generate documentation into the subdirectory, which you use to commit only to gh-pages.

This sounds pretty convoluted but the process has been mapped out here and here. I did this on my fork (results here) and have included the commands I used below:

# Assuming we are starting from the top of the madness directory structure
# Checkout the master branch and add the html documentation directory to .gitignore
git checkout master
echo "doc/html/" >> .gitignore
git add .gitignore
git commit -m "Added html documentation folder to .gitignore."
git push origin master

# Now clone the entire project into the html directory
cd doc/html/

# Remove any documentation that is currently in this folder
rm -f *.png
rm -f *.html
rm -f *.map
rm -f *.md5
rm -f *

# Clone stuff
git clone git@github.com:m-a-d-n-e-s-s/madness.git .
git checkout -b hg-pages

# Remove the master branch from within the html folder
git branch -d master

# Remove the files and folders from the master branch
# This step may seem scary but everything will be okay
git rm -r src doc config configure.ac LICENSE Makefile.am autogen.sh INSTALL

# Check to see if there is more stuff leftover from master branch. If so, remove it
git commit -m "removed everything from gh-pages branch"

# May want to edit the .gitignore file as well to remove unnecessary lines

# Now we can checkout the master branch and make the doxygen documentation
cd ..
git checkout master
doxygen doxygen.cfg
cd html
git checkout gh-pages

# bash got mad at me about adding too many arguments at once so I had to add in stages
git add *.png
git add *.map
git add *.md5
git add *.html
git add *
git commit -m "added all html documentation"
git push origin gh-pages

Now, we should have the current doxygen documentation on github. You can see the example from my fork at http://richford.github.io/madness. I'm guessing the m-a-d-n-e-s-s one will be at http://m-a-d-n-e-s-s.github.io/madness.

To keep the documentation updated, the workflow would look something like

# Do development stuff
git push origin master
doxygen doc/doxygen.cfg
cd doc/html
git push origin gh-pages

Perhaps this last part could be automated with Travis-CI