Documenting VTK with doxygen ---------------------------- Sebastien BARRE (Time-stamp: <2001-10-24 22:38:42 barre>) This file describes how to generate a Doxygen-compliant documentation featuring cross-references between classes and examples, a full-text index and an accurate VTK version. Note that this file describes how to run the scripts manually, which can be tedious (to say the least). A batch file doc_makeall.sh is now used to automate this process. It is part of the CMake/Build process and is configured both though CMake and through its own parameter. It should be pretty straightforward to understand and adapt. Warning ------- These scripts are now part of the VTK source distribution. Think twice before letting Doxygen eat your CPU cycles: Kitware is now using these scripts to build an up-to-date Doxygen-compliant documentation every night as part of the "nightly build" process. Thus, you might browse or download a pre-built documentation here: http://public.kitware.com/doc/ Nevertheless, Doxygen might still be useful to generate additional PDF, Postscript or plain LaTeX output. This package is made of he following Perl scripts: - doc_header2doxygen.pl: convert the VTK headers to the Doxygen format - doc_version.pl: extract the VTK version and add it to the documentation set - doc_class2example.pl: build cross-references between classes and examples - doc_index.pl: build the full-text index Use the --help option to display the parameters that are allowed for each script. Thanks to Vetle Roeim and Jan Stifter who started the project :) A. Preamble -------- I assume that your VTK distribution is in a 'VTK' directory and that you do NOT want to modify it in any ways. You would rather create a modified copy of the VTK files in a different location (here, the '../VTK-doxygen' directory, assuming that you are in the 'VTK' directory now). Hence, you might use this main 'VTK' directory for CVS and development purposes (updating it from time to time) and rerun the process described below to update your documentation (a straightforward process once you get used to it). The Perl scripts described in that document are stored in the 'VTK/Utilities/Doxygen' directory. You will also find a couple of additional files like a VTK logo and a batch script automating the whole conversion process. Thus, the directories that are of some interest in that README are: VTK/ : the VTK repository VTK/Utilities/Doxygen : the Doxygen scripts and configuration files VTK-Doxygen/ : the intermediate VTK repository The doxygen configuration script, i.e. the script controlling how this VTK documentation is created, is named 'doxyfile'; it is also stored in the 'VTK/Utilities/Doxygen' directory. It is read by doxygen and lists option/value pairs like: PARAMETER = VALUE Comment lines are allowed and start with '#'. Commenting a directive is a simple way to hide it to doxygen: # PARAMETER = VALUE Do not forget to set the OUTPUT_DIRECTORY directive specifying the location where the whole documentation is to be stored. Example: OUTPUT_DIRECTORY = ../../../doc The crucial INPUT directive controls which directory or files are processed by doxygen to produce the documentation. Each directory/file is separated by a space. Whenever you will be requested to add a filename to INPUT, just add it to the end of the list. Example: INPUT = ../../../VTK-doxygen/Common ../../../VTK-doxygen/Filtering ../../../VTK-doxygen/Graphics ../../../VTK-doxygen/Hybrid ../../../VTK-doxygen/Imaging ../../../VTK-doxygen/IO ../../../VTK-doxygen/Parallel ../../../VTK-doxygen/Patented ../../../VTK-doxygen/Rendering ../../../VTK-doxygen/doc_version.dox ../../../VTK-doxygen/doc_class2examples.dox ../../../VTK-doxygen/doc_class2tests.dox ../../../VTK-doxygen/doc_index.dox WARNING: disable the HAVE_DOT directive if you have not installed graphviz (http://www.research.att.com/~north/graphviz/download.html). B. Download doxygen, make sure it runs ----------------------------------- http://www.doxygen.org C0. Go to the VTK/Utilities/Doxygen directory ----------------------------------------- You are supposed to run all scripts as well as Doxygen from this directory. For example: D:\src\kitware\vtk\VTK> cd Utilities\Doxygen D:\src\kitware\vtk\VTK\Utilities\Doxygen> C1. Convert the VTK headers to Doxygen format ----------------------------------------- Use the conversion script: doc_header2doxygen.pl For example: D:\src\kitware\vtk\VTK\Utilities\Doxygen> perl doc_header2doxygen.pl --to ../../../VTK-doxygen doc_header2doxygen.pl 0.8, by Sebastien Barre et al. Collecting... Converting... => 729 files converted in 6 s. Finished in 7 s. Meaning that: The optional '--to ../../../VTK-doxygen' parameter specifies that the script stores the modified C++ *headers* (*.h files) in the '../../../VTK-doxygen' directory (here: 'D:\src\kitware\vtk\VTK-doxygen', as I issued the command from 'D:\src\kitware\vtk\VTK\Utilities\Doxygen'). The files located in 'VTK' remain untouched. The script browses the directories located two levels up (i.e. ../../) automatically. Use --help to display the default value associated to --to. Note that you might restrict the conversion to a set of particuliar directories or files if you want to document a specific VTK part only: just add these parts as parameters. Example: D:\src\kitware\vtk\VTK\Utilities\Doxygen> perl doc_header2doxygen.pl --to ../../../VTK-doxygen ../../Hybrid Update the Doxygen configuration file ('doxyfile'): Depending on the location from where you are going to run Doxygen (here: 'D:\src\kitware\vtk\VTK\Utilities\Doxygen') update or add the paths to the VTK components/directories that you want to document. Since the headers have been created in '../../../VTK-doxygen', the following values will be fine: INPUT = ../../../VTK-doxygen/Common ../../../VTK-doxygen/Filtering ../../../VTK-doxygen/Graphics ../../../VTK-doxygen/Hybrid ../../../VTK-doxygen/Imaging ../../../VTK-doxygen/IO ../../../VTK-doxygen/Parallel ../../../VTK-doxygen/Patented ../../../VTK-doxygen/Rendering C2. Extract VTK version ------------------- Use the extraction script: doc_version.pl For example: D:\src\kitware\vtk\VTK\Utilities\Doxygen> perl doc_version.pl --logo "vtk-logo.gif" --to ../../../VTK-doxygen doc_version.pl 0.22, by Sebastien Barre => 4.0.0 => $Revision$ $Date$ Building version documentation to ../../../VTK-doxygen/doc_version.dox Finished in 0 s. Meaning that: The optional '--to ../../../VTK-doxygen' parameter specifies that the script stores the related documentation part in the '../../../VTK-doxygen' directory (more precisely in the '../../../VTK-doxygen/doc_version.dox' file). The VTK logo is incorporated by using the --logo option. The script searchs for the VTK version in the '../../Common/vtkVersion.h'. Use --help to check how to override these default values. Update the Doxygen configuration file ('doxyfile'): Comment the PROJECT_NUMBER directive: you do not need it anymore as you have just created a more accurate description based on the current vtkVersion.h. # PROJECT_NUMBER = C3. Generate the 'class to examples' pages -------------------------------------- Use the referencing script: doc_class2example.pl For example: D:\src\kitware\vtk\VTK\Utilities\Doxygen> perl doc_class2example.pl --link http://public.kitware.com/cgi-bin/cvsweb.cgi/~checkout~/VTK/Utilities/Doxygen --to ../../../VTK-doxygen doc_class2example.pl 0.7, by Sebastien Barre Collecting files... => 17 file(s) collected in 2 s. Parsing files... => 17 file(s) parsed in 0 s. Eliminating some classes... => 1 class(es) eliminated (vtkCommand) in 0 s. Locating headers to update... => 33 found, 8 orphan class(es) removed (vtkIOJava, vtkRenderingJava, vtkCommonJava, vtkImagingJava, vtkGraphicsJava, vtkInteract, vtkTkWidget, vtkFilteringJava) in 0 s. Building classes doc and alphabetical section(s) weight(s)... => 33 classes(s) documented in 0 s. => total weight is 38604 in 13 section(s) (mean is 2969) Computing alphabetical group(s)/page(s)... => max weight is 90000 per group/page, but a section can not be divided => 1 group(s) for 13 section(s) Building pages header... Writing documentation to ../../../VTK-doxygen/doc_class2examples.dox... - 33 class(es) in 17 file(s) from directories matching @c ^Examples$ on Mon Oct 1 10:53:04 2001 - 4 parser(s) : [Java, Python, C++, Tcl] - at most 20 file(s) per parser (0% over) => in 0 s. Updating headers... => 32 header(s) updated in 0 s. Finished in 2 s. Meaning that : The optional '--to ../../../VTK-doxygen' parameter specifies that the script searches (and parses) the Python, Tcl, Java or C++ *examples* (17 here) in the directories two level up (i.e. ../../ and below) but updates the C++ class *headers* (32 here) stored in the '../../../VTK-doxygen' directory (which is good because they have just been created in step C1). These headers are updated to include cross-links between the class and the examples using it. The script stores the documentation file listing all examples in the '../../../VTK-doxygen/doc_class2example.dox' file. Once again, the files located in 'VTK' remain untouched. The --link option is a path or a URL that is prepended to each example's name to provide a physical link to that example (here, the CVSweb). Use --help to check how to override these default values. More specifically you can override the --dirmatch option (a regexp) so that the parsers will only look into specific directories. The default value "^Examples\$" constrains the script to any directory which name is 'Example'; --dirmatch "^Testing$" will actually make the script parse all examples found in the 'Testing' directories (the --label, --title and --unique option should be changed appropriately, check 'doc_makeall.bat' for example). Update the Doxygen configuration file ('doxyfile'): Add the relative path to 'doc_class2example.dox' (here : '../../../VTK-doxygen/doc_class2example.dox') to the INPUT directive, so that Doxygen might process it (see also section D). C4. Build full-text index --------------------- Use the indexing script: doc_index.pl For example: D:\src\kitware\vtk\VTK\Utilities\Doxygen> perl doc_index.pl --to ../../../VTK-doxygen doc_index.pl 0.2, by Sebastien Barre Reading stop-words from doc_index.stop... => 724 stop-word(s) read. Collecting files... Indexing... => 8174 word(s) grabbed in 729 file(s) in 2 s. Removing... => 3126 word(s) removed. Grouping... => 2075 word(s) grouped. Normalizing... => normalized to lowercase. Building indexes doc and alphabetical section(s) weight(s)... => 2973 words(s) documented in 2 s. => total weight is 400800 in 47 section(s) (mean is 8527) Computing alphabetical group(s)/page(s)... => max weight is 90000 per group/page, but a section can not be divided => 6 group(s) for 47 section(s) Building pages header... Writing documentation to ../../../VTK-doxygen/doc_index.dox... - 729 file(s) indexed by 2973 word(s) on Mon Oct 1 11:13:44 2001 - max limit is 10 xref(s) per word Finished in 5 s. Meaning that: The optional '--to ../../../VTK-doxygen' parameter specifies that the script stores the full-text index in the '../../../VTK-doxygen' directory (more precisely in the '../../../VTK-doxygen/doc_index.dox' file). The optional --stop parameter can be used to specify that the script should read its stop-words from a different file (default is 'doc_index.stop'). This file is a list of trivial words (one per line) that won't be indexed. Update the Doxygen configuration file ('doxyfile'): Add the relative path to 'doc_index.dox' (here : '../../../VTK-doxygen/doc_index.dox') to the INPUT directive, so that Doxygen might process it (see also section D) D. Run doxygen ----------- Check that your Doxygen configuration file is OK ('doxyfile'). The important directives are: PROJECT_NAME = VTK # PROJECT_NUMBER = OUTPUT_DIRECTORY = ../../../doc INPUT = ../../../VTK-doxygen/Common ../../../VTK-doxygen/Filtering ../../../VTK-doxygen/Graphics ../../../VTK-doxygen/Hybrid ../../../VTK-doxygen/Imaging ../../../VTK-doxygen/IO ../../../VTK-doxygen/Parallel ../../../VTK-doxygen/Patented ../../../VTK-doxygen/Rendering ../../../VTK-doxygen/doc_version.dox ../../../VTK-doxygen/doc_class2examples.dox ../../../VTK-doxygen/doc_class2tests.dox ../../../VTK-doxygen/doc_index.dox Then run doxygen. Be *patient* :) For example: D:\src\kitware\vtk\VTK\Utilities\Doxygen> doxygen The documentation will be located in the '../../../doc' directory. If that directory does not exist, doxygen will create it, *unless* the its parent directory does not exist either. You are done. Browse the HTML documentation starting from: doc/html/index.html Just my 2 cents. Sebastien BARRE