Doxygen / Subversion Integration Instructions


The following are instructions on generating Doxygen documentation of Subversion trunks, adding the doco into the same SVN trunk for versioning and automatically backing up. I couldn't find any documentation on this online so fingured I'd share my findings.

The idea here is for Doxygen to scan specified files within Subversion and generate documentation. Once this documentation is created, it is compressed into a single file which is immediately placed back into Subversion for versioning. If a versioned source code checkout is ever needed, the same versioned Doxygen code is along-side in the repository.

Lets start off my making our new storage directories; one for the SVN files and one for the HTML documentation. I split these into multiple directories under “svn” and “html”.
*Replace <name> with desired directory names.

1. mkdir /mnt/sdc1/doxy/svn/<name>
2. mkdir /mnt/sdc1/doxy/html/<name>

Now let's get the newest version of the source code that we need.

3. svn checkout <repo-location> /mnt/sdc1/doxy/svn/<name>

I have created a simple bash script for automating the backup process. Let's go ahead and edit the script for our new directories.

*Doxygen must be fully installed and configured before running the following script.
*Set Doxygen “input location” to the doxy/svn directory and “output” to doxy/html

Trunk Script -

sudo svn cleanup /mnt/sdc1/doxy/svn/<name>
sudo svn update /mnt/sdc1/doxy/svn/<name>
sudo svn del /mnt/sdc1/doxy/svn/<name>/doxygen.tar.gz
sudo doxygen <doxygen-config-file>
sudo rm -rf /mnt/sdc1/doxy/html/<name>/latex
sudo rm -rf /mnt/sdc1/doxy/html/<name>/html/*.gz
sudo tar -zcf /mnt/sdc1/doxy/svn/<name>/doxygen.tar.gz /mnt/sdc1/doxy/html/<name>
sudo svn add /mnt/sdc1/doxy/svn/<name>/doxygen.tar.gz
sudo svn commit /mnt/sdc1/doxy/svn/<name> -message


Script Explained:

sudo svn cleanup /mnt/sdc1/doxy/svn/<name>
-Cleans up the SVN directory to minimize automated corruption.
sudo svn update /mnt/sdc1/doxy/<name>
-Updates the changed files and revisions from Subversion
sudo doxygen <doxygen-config-file>
-Runs Doxygen on the newly checked-out repository
sudo rm -rf /mnt/sdc1/doxy/html/<name>/latex
-Removes unwanted “Latex” files (Optional)
sudo rm -rf /mnt/sdc1/doxy/html/<name>/html/*.gz
-Deletes the previously versioned Doxygen
sudo tar -zcf /mnt/sdc1/doxy/svn/<name>/doxygen.tar.gz /mnt/sdc1/doxy/html/<name>
-Compresses the newly generated Doxygen and places tar.gz back into SVN directory
sudo svn add /mnt/sdc1/doxy/svn/<name>/doxygen.tar.gz
-SVN adds the Doxygen tar.gz
sudo svn commit /mnt/sdc1/doxy/svn/<name> -message
-Commits the SVN directory with the new Doxygen

This script can be duplicated and modified for multiple Doxygen scans. Personally, my primary backup script calls a number of these Doxy scripts to generate and compress the documentation, then SVN dump commands immediately backup the entire repository.

Additionally, Apache aliases can be created for viewing the most recent version of the documentation. TracHack's Doxygen plug-in is also useful for creating quick “hot-links” to Doxygen alongside Subversion.

Hope this will help someone.