As I’ve been working on my RenameTV project recently, I thought it about time to start properly and formally documenting my code. For automatic documentation generation there is doxygen, which is fantastically well supported and pretty much always works like a charm. It can create very detailed and cross-referenced documentation in many formats including HTML and LaTeX.

GitHub also has some nice functionality, called GitHub Pages, in which you can create a branch of your project called gh-pages, and anything committed and pushed back to origin gets published as a web page.

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 comit only to gh-pages.

It sounds a lot more convoluted than it is, and setting it up is simple bit long-winded. Thankfully, someone very clever has already submitted a gist to walk you through the process. Find it here, and enjoy!!