How to generate the BoA documentation using Doxygen

First steps

• Download and install Doxygen. See http://www.stack.nl/~dimitri/doxygen/

• Then you'll need to copy the following files to your ./doc directory:

  1. /user1/cvlahaki/boa_20061110/openboa_wo_iraf/doc/boa-config-030807

  2. /user1/cvlahaki/boa_20061110/openboa_wo_iraf/doc/boa_master_doc.tex

  3. /user1/cvlahaki/boa_20061110/openboa_wo_iraf/doc/doxygen_out/doxygen-mine.sty

Basic Information

boa-config-030807 is the config file for Doxygen which contains all the setup, input and output information. It is currently configured to do the following main things:

• take the file boa_master_doc.tex as input.

• document certain .py files which are in the boa directory (for making the appendices).

• produce latex output in a directory called ./doxygen_out

Next Steps

(i.e. steps you must follow before you're ready to produce the documentation INCLUDING APPENDICES ( i.e. using Doxygen)).

• Create the directory ./doxygen_out in ./doc and in it put the file doxygen-mine.sty.

• Make sure that the config file boa-config-030807 is located in ./doc and not in the ./master directory. The reason for this was that the ./master directory was what we used for just parts 1 and 2, i.e. only as a working directory.

• Make sure that you're using the file /user1/cvlahaki/boa_20061110/openboa_wo_iraf/doc/boa_master_doc.tex (and not the one in ./master, which deals only with parts 1 and 2 of the documentation and doesn't know anything about Doxygen).

• Modify the list of .py files in boa-config-030807 if necessary. Currently they are the ones Frederic felt were needed ( e.g. BoaDataEntity.py). If new files exist that need to be documented in the appendices then add them in the boa-config-030807 file. I found it was better to list the ones we want, rather than to just parse all .py files because

  1. we don't want to document them all and
  2. when there are "mistakes" in the documenting of the code which Doxygen can't deal with (e.g. ##) it is then impossible to locate the problem. Better to include the files needed one by one. This is the most likely problem you'll encounter. Check the code.

• Check whether your ./doc directory is located at the same level as your boa directory (where the .py files are located). If not then you'll have to change the paths for the INPUT tag of the config file boa-config-030807 (in the section configuration options related to the input files).

Final Steps

When you're ready to produce the documentation just type

• Doxygen boa-config-030807

in the ./doc directory (where ./doxygen_out, boa-config-030807 and boa_master_doc.tex must be located). This will produce output in the directory ./doxygen_out.

Note that if you haven't created the ./doxygen_out directory already Doxygen will create it for you, but this will not work because you won't have the correct style file (doxygen-mine.sty). Follow all the above steps first.

Do a make in doxygen_out and refman.pdf will be your final pdf documentation output. Check that it includes the appendices (if it doesn't, make sure you carried out the steps above)!

To produce the html version I simply used latex2html on the file refman.tex.