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
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.
I should note here that the make rules will not work on OS X. I use
-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
being empty. Or perhaps remove the
-r and change
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:
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.