You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
331 lines
13 KiB
331 lines
13 KiB
2 years ago
|
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
|