Mere Idea Development Blog

Current Repository Revision: 20

The previous post discussed how Doxygen can be used to produce on-line documentation of C++ code from structured comments. The methods outlined in that post have now been applied to the main mi_test_scons example code. The resulting documentation can be found here.

So that the documentation is always up-to-date, a cron job has been added to build the documentation overnight. The following script is used to do this:

#!/bin/sh
#
# Run the Doxygen command over mi_test_scons, and publish
# the results
#

echo "Starting Doxygen script (mi_test_scons)"
cd /dir/containing/mi_test_scons

# Get the latest code
svn up

# Get rid of the old files, run Doxygen,
# and then go to the produced html directory
rm -Rf docs/html
rm -Rf docs/latex
time doxygen
cd docs/html

# Copy the tab image files, remove old published
# documentation and move the new stuff in its place.
cp ../html_files/*.gif .
rm -Rf /wherever/webpages/are/docs/mi_test_scons/*
mv * /wherever/webpages/are/docs/mi_test_scons/

# Make the pdf and copy to web space
cd ../latex/
make
cp refman.pdf →
   /wherever/webpages/are/docs/mi_test_scons/mi_test_scons.pdf

echo "Done"

It’s pretty straightforward, and doesn’t require much explanation, but there are some things to note.

Firstly, when I initially tried to use this script I discovered that, in my Linux environment, cron used a different Subversion executable than the one called by logged in users. The version called by cron (/usr/bin/svn) was older than the one called by users (/usr/local/bin/svn) and so caused errors, warning about a need to upgrade. To solve this problem soft links were created from all the Subversion executables (svn, svnadmin, svnlook, etc.) in /usr/bin to their equivalent in /usr/local/bin. The old executables were kept in /usr/bin by renaming them with the suffix _bin in case of later problems where we may need to recover them. For example:

cd /usr/bin
mv svn svn_bin
ln -s /usr/local/bin/svn svn
mv svnadmin svnadmin_bin
ln -s /usr/local/bin/svnadmin svnadmin
...

The second thing to note is that we also build the PDF version of the documentation from the Doxygen latex build. This is all automatic once the Doxyfile latex variables are set:

GENERATE_LATEX        = YES
LATEX_OUTPUT          = latex
PAPER_TYPE            = a4
PDF_HYPERLINKS        = YES
USE_PDFLATEX          = YES

When Doxygen is run with these settings, a Makefile will be created in the ./docs/latex directory. Typing make in that directory will then generate the file refman.pdf containing all the documentation, as can be seen from the cron job script. The resulting PDF file can be seen here.

The version of Doxyfile committed to the Mere Idea Subversion repository in the example code has the latex variables set as above.

Finally, the reason the doxygen command is run using the time command (time doxygen) is so that the length of time it takes can be monitored (via the cron-sent email) and the Doxygen build can be split up if it’s taking too long. This can happen in large projects (though it is unlikely with our example).

Licensing

A couple of emails received recently have been giving positive feedback regarding this blog. These are always nice to receive. I welcome any feedback on the blog, including anything you’d like to see discussed (provided it’s related to setting up a development environment). You can give feedback using the Mere Idea contact form.

One thing mentioned in those emails was that it was unclear whether or not the example code could be used by others in their own development environments. As it stands, any of the example code from this blog is free to be used by anybody. To make its availability for use more explicit, I have now licensed the code under the GNU General Public License Version 3 (GPLv3).

If my understanding of the license is correct, this means that any other parts of your development environment that are derived from the Mere Idea code will need to be licensed under the GPLv3 (it’s only fair! I’m sharing my ideas with you, so you should really share too! ), but any code produced using that environment would not need to be GPLv3 licensed (as it wouldn’t actually be derived from any of the GPL’d code). This license is also compatible with the MIT license used by SCons.

If my understanding is wrong, please feel free to contact Mere Idea with a correction. I’m no lawyer!

---

Revision 19 of the example code added the Doxygen and GPLv3 comments to all source files, as well as the committing the Doxygen support files (configuration file, introductory page, etc.). The docs directory was also added (along with the html_files directory containing tab images and style sheet), as well as the main license document (LICENSE.txt).

Revision 20 added some Doxygen markup to the LICENSE.txt file so it appears in the code documentation.

The next post will see a return to SCons, adding a new library to test the ‘configure’ style checking, and then on to how to include replacement code for missing library functions.