Doxygen for a project managed with git?

Question

I'm working on a C++ and Objective C iPhone Project. I'm using git as my version control system.

The codebase has been growing quite a bit, so I would like to add doxygen to the project. The problem is that I'm not sure about what would be the best approach to do it.

I've thought about a couple of options:

1) Create the doxygen HTML documentation in the project folder and make it "part" of the project so that it is also versioned and committed to git.

2) Create the doxygen HTML documentation in the project folder and add it to the .gitignore so each user of the project is responsible for generating the docs and the project git repository would remain untouched (except for the .gitignore).

We are using a git --bare repository in our main server, so to mount a webpage containing the HTML doxygen in the server would be complicated ( you can't actually see the project files with a git --bare repo, so I won't be able to see the doxygen generated HTML doc unless I uploaded it separately )

Maybe I could make some kind of cron-job, to keep the doxygen updated on the server side ?

Help is very welcome.

Answer 1

I believe one should never store generated files in a source repository, particularly when they're generated by commonly-available tools like Doxygen from files that are already stored in the repository. In the case of Doxygen, you only need to store Doxyfile in the repo.

(Or, better, if you're using autoconf, store Doxyfile.in, so that the current project version number gets substituted into the generated Doxyfile as part of the configure step.)

If you want to ensure that everyone who checks your project out gets a copy of the Doxygen-generated reference manual, make it part of the default build process.

Answer 2

I agree with Warren, but I would add the following:

You can use a ''post-receive hook'' to automatically update a (separate) working directory every time there's a push to the bare repository. This approach is described for maintaining version-controlled web sites here http://toroid.org/ams/git-website-howto, and I use it that way.

It seems reasonable to me that you could add a step to the hook to run Doxygen after the update, which would be about what you're looking for. You might need to think about how to report errors to the user/committer if Doxygen borks, but that's the only issue I see.