Not bad. Any way to strip the ierr = and CHKERRQ(ierr); from all the html versions of the source code. I find it cluttering and ugly.
Barry On Jan 12, 2013, at 3:10 PM, Karl Rupp <rupp at mcs.anl.gov> wrote: > 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
