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: 1.4 $ $Date: 2001/10/25 02:48:20 $
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