[DOC] doxygen documentation (updates)

Sat Apr 15 13:02:56 EDT 2000

Hi

The VTK - doxygen project is still there :)
http://www.medres.ch/~jstifter/vtk/docu.html

My own contrib is here :

ftp://sic.sp2mi.univ-poitiers.fr/pub/barre/vtk/doc/

Today :
	- header2doxygen 0.6
	- class2example 0.4
	- new short HOWTO
           - updated documentation

I've updated the header2doxygen script to 0.6 :
ftp://sic.sp2mi.univ-poitiers.fr/pub/barre/vtk/doc/header2doxygen.pl

# 0.6 (barre) :
#   - change (warning) default --to to '../vtk2' because I ruined my own
#     VTK distrib too many times :(
#   - add automatic creation of missing directory trees
#   - add check for current OS (if Windows, do not perform tests based
#     on stat()/idev/ino features)

I've updated the class2example script to 0.4:
ftp://sic.sp2mi.univ-poitiers.fr/pub/barre/vtk/doc/class2example.pl

# 0.4 (barre) :
#   - change (warning) default --to to '../vtk2' because I ruined my own
#     VTK distrib too many times :(
#   - change (warning) --to is now a path to a destination directory, and
#     no more a path to the destination doxygen file. The headers to update
#     will logically be searched here, while the examples to process are
#     searched in the directory where the script is launched

New short HOWTO :
------------------------------

Documenting VTK with doxygen.

I assume that your VTK distribution is in a vtk/ directory and that you do 
NOT want to modify it in any ways, but rather produce a modified copy of 
these files in a different location. Hence, you might use this main vtk/ 
directory for CVS purposes (updating it from time to time), and rerun the 
process described below to update your documentation.

1. Download doxygen, make sure it runs

2. Convert the VTK headers to doxygen format

      Use the conversion script : header2doxygen.pl

For example :

      E:\src\vtk\vtk> perl header2doxygen.pl --to ..\vtk2

      header2doxygen.pl 0.6, by V. Roeim, S. Barre
      Converting...
      620 files converted in 8 s.

Meaning that :

      The '--to ..\vtk2' means that the *headers* (*.h and so on) are 
searched in the current directory, but the modified versions are put in the 
vtk2/ directory. Your vtk/ files are untouched.

3. Generate the 'class to example' table

      Use the conversion script : class2example.pl

For example :

      E:\src\vtk\vtk> perl class2example.pl --to ..\vtk2

      class2example.pl 0.4, by S. Barre
      Collecting files...
       => 896 file(s) collected in 3 s.
      Parsing files...
       => 896 file(s) parsed in 1 s.
      Eliminating some classes...
       => 1 class(es) eliminated (vtkCommand) in 0 s.
      Locating headers to update...
       => 394 found, 10 orphan class(es) removed (vtkImageShortReader, 
vtkImageAdaptiveFilter, vtkMINCReader, vtkImageXViewer, vtkImageMIPFilter, 
vtkImageConnectivity, vtkInteract, vtkImageMarkBoundary, 
vtkImageSubSampling, vtkImageRegion) in 1 s.
       Building documentation to ..\vtk2/class2example.dox...
        => VTK 3.1.1, $Revision: 1.488 $, $Date: 2000/04/15 00:08:20 $ (GMT)
        => 394 class(es) examplified by 896 file(s) on Sat Apr 15 18:32:23 2000
        => 3 parser(s) : [Python, C++, Tcl]
        => max limit is 20 example(s) per parser (8% over)
        => in 0 s.
       Updating headers...
        => 393 header(s) updated in 2 s.
       Finished in 7 s.

Meaning that :

      The '--to ..\vtk2' means that the *examples* (896 here) are searched 
in the current directory, but the *headers* (393 here) that have to be 
updated to include a cross-link between the class and its examples are 
searched and updated in the vtk2/ directory (which is good because they 
have just been created in the previous step). The documentation file 
describing/listing all examples is stored in the ..\vtk2/class2example.dox 
file. Your vtk/ files are untouched.

      In that example, my vtk/ directory is 27.7 Mo, and the resulting 
vtk2/ is 3,43 Mo.

4. Run doxygen

      Open you doxygen configuration script (ex: doxyfile), and add 
class2example.dox (the file describing all examples) to the INPUT 
directive. Comment the PROJECT_NUMBER directive, you do not need it, 
class2example will produce a more accurate description based on the current 
vtkVersion.h.

      Depending on the location of this file, update the paths to the 
components to document. My doxyfile is in the VTK directory (vtk/), as well 
as the Perl scripts (header2doxygen, class2example) :

     OUTPUT_DIRECTORY     = ../doxygen-doc
     #PROJECT_NUMBER       =
      INPUT                = ../vtk2/common ../vtk2/contrib 
../vtk2/graphics ../vtk2/imaging ../vtk2/patented ../vtk2/class2example.dox

Here is my doxyfile :
ftp://sic.sp2mi.univ-poitiers.fr/pub/barre/vtk/doc/doxyfile

      run doxygen, be patient, and you are done :)

For example :

      E:\src\vtk\vtk> doxygen

The documentation will be located in ../doxygen-doc

Updated documentation
------------------------------

Following the process described above, I've generated HTML documentation as 
well as a Windows Compressed HTML file (very practical) :

ftp://sic.sp2mi.univ-poitiers.fr/pub/barre/vtk/doc/index.chm
ftp://sic.sp2mi.univ-poitiers.fr/pub/barre/vtk/doc/vtk-doc.tar.gz

--
Sebastien BARRE
IRCOM-SIC, UMR-CNRS 6615 - Université de Poitiers
Bât. SP2MI, Bvd 3 - Téléport 2, BP 179 F-86960 Futuroscope Cedex
Tel. : +33 (0)5 49 49 65 95 / 65 83, Fax : +33 (0)5 49 49 65 70
http://www-sic.univ-poitiers.fr/barre/ ou  http://www.hds.utc.fr/~barre/
--------------------------------------------------------------------
This is the private VTK discussion list. Please keep messages on-topic.
Check the FAQ at: <http://public.kitware.com/cgi-bin/vtkfaq>
To UNSUBSCRIBE, send message body containing "unsubscribe vtkusers" to
<majordomo at public.kitware.com>. For help, send message body containing
"info vtkusers" to the same address.
--------------------------------------------------------------------