Problems building doxygen docs

[Sebastien Barre]

At 14:23 13/04/00 -0400, Aleksey Naumov a écrit:

>Dear Sebastien and Vetle (and everybody),
>
>I am trying to build docs with doxygen using your scripts and having two
>problems.
>
>1. One is minor - header2doxygen.pl complains that it's unable to create
>a destination file:
>
>[lesha at Chinara vtk]$ perl ../vtk_doxygen/header2doxygen.pl --to ../vtk2
>header2doxygen.pl 0.5, by V. Roeim, S. Barre
>Converting...
>header2doxygen.pl: unable to open destination file ../vtk2/common/vtk.h

[...]

Ooops, my fault :)
I've just fixed it, and version 0.6 is now able to create missing directory 
trees/path automagically.

But indeed I forgot that feature because it did not make much sense, and 
here is why :

>2. Another problem is with class2example script - it bugs out. Here's
>the info:
>
>[lesha at Chinara vtk2]$ perl ../vtk_doxygen/class2example.pl
>class2example.pl 0.3, by S. Barre
>Collecting files...
>  => 0 file(s) collected in 1 s.
>Parsing files...
>  => 0 file(s) parsed in 0 s.
>Eliminating some classes...
>  => 0 class(es) eliminated () in 0 s.
>Building documentation to class2example.dox...

It's not a bug :) class2examples tries to process example files and create 
a description page as well as cross-links between class headers and 
examples (if needed).

But as it implies, I needs examples files !

And there are *no* examples files in you vtk2/ directory, header2doxygen 
does just translate/copy *headers* to doxygen format, it does not handle 
examples files which are written in Tcl, Java, Python, and so on (doxygen 
does understand C++, nothing else). Thus, examples that were in the vtk/ 
directory, were neither copied nor moved or translated to the vtk2/ directory.

Hence, you have to launch class2examples in a directory that contains the 
VTK examples.

2 solutions :

1) actual solution (here is how I did before) :

Until class2examples version 0.3, the directory containing the examples had 
to hold the doxygen-modified headers too (step performed by 
header2doxygen), because they were going to be updated to add a link from 
each class to the corresponding example section.

Thus, you could copy the examples directories from vtk/ to vtk2/, but as 
you imagine there are *a lot* of them, that would just be to painful and 
you would forget one of them, or modify the directory tree.

The solution was (and that's the reason why I forgot your problem '1') :

         Make a copy of your *whole* VTK directory : vtk/ -> vtk2/
         then do as usual :
                 vtk> perl header2doxygen.pl --to ..\vtk2
                 vtk> cd ../vtk2
                 vtk2>perl class2example.pl

As a faithful copy, vtk2/ would contain both the correct directory 
hierarchy (which solves problem 1), and the examples (which solves problem 2).

2) better solution.

Actually, your suggestion is good, hence I fixed class2examples so that the 
--to option might be used just like header2doxygen. The resulting procedure 
is cleaner, simpler, and the destination directory is now much smaller :

Let's say that you do NOT want to modify your vtk/ directory at all (which 
is my case, as I'm updating it with CVS) :

                 vtk> perl header2doxygen.pl --to ..\vtk2
                 vtk> perl class2example.pl --to ..\vtk2
                 vtk> doxygen

and you are done !

Step 1 will create the vtk2 directory for you, you do NOT need to copy vtk/ 
to vtk2/.
Step 2 will search for the examples in the current directory (vtk/) but 
will UPDATE the headers located in the vtk2/ directory (which is good, they 
just have been translated in step 1)
Step 3 will launch doxygen.

both header2doxygen, class2example, and doxyfile just have to be in your 
vtk/ directory.
In that case, doxyfile has to be modified like this :

INPUT                = ../vtk2/common ../vtk2/contrib ../vtk2/graphics 
../vtk2/imaging ../vtk2/patented ../vtk2/class2example.dox

Hope it helps :)

I will send a new "short howto" to the list.

--
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.
--------------------------------------------------------------------