HowTo: Use Doxygen with GitHUB.

Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout - a step-by-step guide. — Gist

And thanks to Tim Jones for appearing in google first, and selling me on the idea:
http://www.freakinabox.com/2011/03/04/using-doxygen-with-gh-pages-on-github/

GitHub is a dashboard for software development. It has the usual SCM, Bug Tracking, Wiki, web site, etc. For design documentation, Doxygen is the way to go. It scans all of your source code, collects, indexes, and cross references your comments and creates a document. If you could generate Doxygen documents along with your code, use the GitHub web site feature, your project would always have up to date design documentation.

GitHub doesn't do this out of the box. Here is the best way I've found to do it for now.

When you get done, you will have a GitHub project like this:
https://github.com/rickfoosusa/openbenchmarks

With  up to date Doxygen documentation like this:
http://rickfoosusa.github.com/openbenchmarks

The traditional gh-pages branch in GitHUB is for static pages associated with your project. This is done by adding web content to a branch named "gh-pages".
http://pages.github.com

Doxygen is a tool that generates a design document based on comments placed in your source code. The Doxygen output document can be a group of html pages.
http://www.stack.nl/~dimitri/doxygen/index.html

Combining the documentation and source code in a single file has proven to be the best way to keep design documentation up to date.The problem using GitHub with Doxygen is that the source goes away when you switch to the gh-pages branch. You need the source code to generate the Document.

Although layers and submodules may be better, one way to do this is to create a gh-pages branch as a sub-directory called html in your local checkout of master. Then you run doxygen HTML_OUTPUT into that directory, push both master and gh-pages, and it displays on your project GitHub page.

So if your master checkout has a gh-branch checked out in a subdirectory called html, and your Doxyfile points to it, you will be able to push the latest detail design doc changes up to github on every commit. This is a manual step, and so a better method needs to be done, at a later time, probably by someone else...

So from the above link, the commands to do this follow. GitHub likes each project or branch to have a README file. There are a variety of filters that make them appear on the GitHub web site. The example includes markdown, and textile formats.

First, create your project in GitHub. Go to the admin pages and enable gh-pages for your project. You will need the gh-pages branch created by GitHub, and whatever initialization it does.

# Make your gitHub project. 

mkdir project
cd project/
git init
echo "# Project README file" > README.markdown
git add .
git commit -m "Project README added"
git remote add origin git@github.com:rickfoosusa/project.git
git push origin master

# Make a new html directory, and tell git to ignore it. 

mkdir html
echo "html/" > .gitignore
git add .
git commit -m ".gitignore html/ folder (contains gh-pages branch)"
git push origin master

# Clone the whole project (master+gh-branch) into a new subdirectory

cd html/
git clone git@github.com:rickfoossusa/project.git .
git checkout origin/gh-pages -b gh-pages
ls -la

# Ignore the warning. Get rid of master, leaving gh-branches.
git branch -d master
 

# You are now on the gh-pages branch.

# You might have an index.html from GitHub, otherwise an empty directory.

git branch 

echo "h1. html README file" > README.textile
git add . git commit -m "html README added"

# Now push the gh-pages back to GitHub.

git push origin gh-pages

# Back to the top of your project. 

cd .. 

At this point, the help ends, and my part of the HowTo begins.

The next steps are how to do Doxygen for the rest of your project.

Create a docs directory for your doxygen files, and add a Doxyfile to configure the system, and a mainpage.dox file to describe your project.

The front page of your Doxygen Document, called mainpage, is blank by default. So when you start a new project, might as well get this in place now.

It's always good to write a paragraph on why you are doing a new project in the first place :)

# From the top of your project

mkdir docs

cd docs

doxygen -g

cat <<EOF >mainpage.dox

/**

@brief Documentation file for Mainpage, and defgroups.

@author Rick Foos at Solengtech dot Com

@file

*/

/** @defgroup Opensource Benchmark Sources */

/**

@mainpage Openbenchmarks - Open Source Benchmark Collection

Why am i doing this, again ...

*/

EOF 

# Edit your Doxyfile, look for the HTML_OUTPUT, leave it blank or set to html. 

vi Doxyfile

# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.

# If a relative path is entered the value of OUTPUT_DIRECTORY will be

# put in front of it. If left blank `html' will be used as the default path.

HTML_OUTPUT = html

We're done. Now you have a master branch to develop code, and a gh-branch to update your Doxygen websiet. When you push the master, run doxygen (doxygen docs/Doxyfile), then cd to html, and push the web site (gh-pages)!

# Manually push master, run doxygen, and push gh-pages each time.

cd project

git push origin master

doxygen docs/Doxyfile

cd html

git push origin gh-pages

# There are others working on automating this, encourage them !

-Rick