= How to generate the BoA documentation using Doxygen =
== First steps ==
 * Download and install Doxygen. See [[http://www.stack.nl/~dimitri/doxygen/|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''
  1. ''/user1/cvlahaki/boa_20061110/openboa_wo_iraf/doc/boa_master_doc.tex''
  1. ''/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
  1. 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''.