For one of my projects I have just started checking generated API documentation into Subversion. This has a few benefits:
- I don’t need separate hosting for the generated API documentation.
- The API documentation benefits from whatever versioning scheme you adopt in Subversion.
- By hooking the script into your release process you can make sure that the documentation is always up to date.
However, there’s a couple of things that may snag you too:
- It requires that your Subversion repository is available over HTTP.
- You have to set the mime-type of the various file types correctly. Otherwise you just get the raw content of each file.
- You have to deal with adding and removing files when the documentation changes.
- Doxygen puts a timestamp in every file so every time you regenerate the documentation all the files will appear to have changed. That’s a lot of unnecessary updates if you’re barely tweaking the version number for a patch release.
If you’re using Google Code your repository is already available over HTTP. The below script snippet deals with the remaining issues. It assumes that you have already run Doxygen and generated documentation in /tmp/doxygen, and that you are running it from your Subversion checkout, and that the directory that contains the API documentation is called apidocs.
rm -f apidocs/*
cp -p /tmp/doxygen/html/* apidocs
cd apidocs
# Revert files that only has one line removed
# and one added. They differ only in the timestamp.
svn diff *.html \
| diffstat \
| awk '$3 == 2 { print $1 }' \
| xargs svn revert
# Add/remove files from subversion.
svn st | awk '
$1 == "?" { print "svn add", $2 }
$1 == "!" { print "svn delete", $2 }
' | sh -
# Set mime-types so files display properly
# rather than just display their raw content.
svn propset svn:mime-type text/html *.html
svn propset svn:mime-type text/css *.css
svn propset svn:mime-type image/png *.png
svn propset svn:mime-type image/gif *.gif
Notice that it doesn’t actually submit the changes, so you can verify that the generated documentation looks like you want it to before you check it in.
