GitHub gh-pages, doxygen and autoconf

Recently I was working on a low level library which I wanted to add a dependent library to. For things like this I really wish they’d have better docs. So if I was going to contribute to the world of lower level libraries I was going to at least try to make some docs for it.

First step was to pick a tool. In the end I went with doxygen which seems to integrate well with autoconf. I set up the build environment and soon had docs that would build locally. Still, that’s a big commitment for a potential user; how can you give a potential developer using your lib a chance to get a quick look at library.

One way is to use GitHub Pages. The way it works is that you put your docs in a special branch - gh-pages - and then you can view them at YOUR-NAME-ON-GITHUB.github.io/YOUR-PROJECT-NAME. Even better you can put a file called CNAME in the base of that branch with the name of the domain you want to be served.

The problem is that it’s a separate branch from your normal branch - typically it’s an orphan branch - and it’s kind of a pain to switch back and forth from. So I wrote a make rule to do it all for me w/o disturbing my tree.

This is the initial setup. You only do this once; I just ran it from the shell.

1
2
3
4
5
6
7
8

mkdir foo
git checkout --orphan gh-pages
GIT_INDEX_FILE=$PWD/.git/index.gh-pages git --work-tree foo status
touch foo/.nojekyll
GIT_INDEX_FILE=$PWD/.git/index.gh-pages git --work-tree foo add .nojekyll
GIT_INDEX_FILE=$PWD/.git/index.gh-pages git --work-tree foo commit -m 'Turn off Jekyll'
git checkout master
rm -rf foo

I should note here that the make rules will not work on OS X. I use the -r flag for xargs which sadly OS X’s xargs does not support. If you use OS X you could modify this to check for ls-files --deleted being empty. Or perhaps remove the -r and change rm to rm -f some.file.you.never.expect.to.exist which would mean rm would always have at least one file. Anyway, this way looks a bit nicer to me so this is what I went with:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

gh-pages: clean
        test `git rev-parse --abbrev-ref HEAD` = master
        rm -f $(PWD)/.git/index.gh-pages
        $(MKDIR_P) docs/html
        GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages git --work-tree $(PWD)/docs/html checkout gh-pages
        $(MAKE) doxygen-doc coverage-html || (git co master; exit 1)
        GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages git --work-tree $(PWD)/docs/html checkout .nojekyll
        GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages git --work-tree $(PWD)/docs/html checkout CNAME
        GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages git --work-tree $(PWD)/docs/html add .
        GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages git --work-tree $(PWD)/docs/html ls-files --deleted | GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages xargs -r git --work-tree $(PWD)/docs/html rm
        GIT_INDEX_FILE=$(PWD)/.git/index.gh-pages git --work-tree $(PWD)/docs/html commit -m "Update docs."
        git checkout master

Now make gh-pages will do a new release of the doxygen docs and the gcov output. The result lives at http://text.protobuf-c.io/ and looks quite well if I do say so myself.