[petsc-dev] PETSc goes Doxygen!?

[Karl Rupp]

Dear PETScians,

as indicated in a previous thread, I spent some time on investigating 
what Doxygen can do for us (thanks to Peter for some pointers). I set 
myself the constraint of not touching any existing sources in order to 
keep the generation of FORTRAN stubs intact.

Actually, it turns out that even under this harsh constraints, Doxygen 
produces good results. Particularly the dynamic tree-view and the search 
feature are very nice. Have a look here:
   http://krupp.iue.tuwien.ac.at/petsc-doxygen/
To keep the effort for this evaluation reasonable, only the first two 
chapters of the user manual are currently migrated.

The doxygen run is not integrated in any makefiles. One needs to run 
doxygen (version 1.8.0 or higher) from petsc-dev/doc by
  $> doxygen ../src/docs/doxygen/Doxyfile

Pros:
   - Three-way-linking:

        Examples
        /       \
  Man-Pages --  Manuals

     I injected a minor test case linking an example with a man page and 
the developer manual:
http://krupp.iue.tuwien.ac.at/petsc-doxygen/docs_2doxygen_2examples_2ex1_8c-example.html
http://krupp.iue.tuwien.ac.at/petsc-doxygen/ex1_8h_a4204a07ed0f7e0571f0b2b934759b6b0.htm
http://krupp.iue.tuwien.ac.at/petsc-doxygen/dev-minimal-class-standards.html

   - Everything in one place
   - Convenient browsing using Tree-View
   - Search feature at the top right (yes, it should be 10x larger...)
   - BibTeX support
   - Just needs simple filters for the existing sources
   - Examples, References and 'Referenced by' automatically provided. I 
think 'Referenced by' should be turned off, but I kept it for 
demonstration purposes.


Cons:
   - The manuals are converted partly by hand (see discussion below)
   - Size: The full output consumes 1GB. Some things can still be turned 
off, though.
   - Link names: The URLs for the man pages contain some hash rather 
than the function name. Former versions of Doxygen used to have the full 
function name in the URL, similar to what sowing produces.
   - Group examples: I haven't found a way to group examples, there's 
only the list of all examples
   - External Dependency rather than 'our own dependency'.


The most time consuming part was/is the migration of the manuals. This 
is partly a technical thing (Doxygen does not parse all LaTeX stuff, so 
this needs to be filtered), but also a semantic thing. For example, in a 
PDF you naturally refer to another Chapter by something like 'as we know 
from Chapter 1 ...', while in an HTML document it is preferable to have 
something like 'as we know from <a>the introductory discussion</a> ...'.

Doxygen allows to have commands for switching between different output 
targets, so in principle it would be possible to transfer the current 
manuals to a markup-time format, which can then be used with doxygen as 
well as for dedicated standalone PDFs as we have it now. For that to 
happen it is essential to come to a conclusion on whether we want to use 
Doxygen in the future, or whether we want to stick with the current 
tools. Barry? ;-)

Best regards,
Karli