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 git@github.com:MY_GITHUB_USERNAME/MY_GITHUB_PROJECT.git;\
git push -u -f origin gh-pages