Github has a cool feature – it allows you to attach html pages to your repo. And if the web pages designer that brings memories of early 00s is somewhat useless – storing doxygen html docs there is a very cool feature.
However we can’t store any history in gh-pages branch. It would be utterly useless and may heavily bloat the repo (especially if you generate a plenty of diagrams with graphviz). So ideally we should:
- Make a clean branch each time, commit all the docs we’ve generated
- Do –force push, so that we’d drop everything on the remote side
- Do it from our development branch, without switching to gh-pages
- Potentially integrate with CI/Jenkins: Build succeded, unit-tests passed, static analysis okay – bump the docs!
Can be achieved easier than it sounds. Here’s my quick sniplet for this hackery in GNU/Make:
doxygen: -rm -Rfv doxygen/ ( cat Doxyfile ; echo "PROJECT_NUMBER=0.1" ) | doxygen cd doxygen/html;\ rm -Rfv .git;\ git init .; git checkout --orphan gh-pages;\ git add *;\ git commit -m "documentation-for-gh-pages";\ git remote add origin email@example.com:MY_GITHUB_USERNAME/MY_GITHUB_PROJECT.git;\ git push -u -f origin gh-pages