Hi, > Any way to strip the ierr = and CHKERRQ(ierr); from all the html versions of the source code. I find it cluttering and ugly.
It doesn't work 'directly' as Doxygen currently does not apply filters to examples. The remedy is an additional copy&conversion step, i.e. something comparable to $> cp -R src/ tmp/ $> find tmp/*/examples/tutorials/*.c | xargs sed -i 's/ierr = //g' $> find tmp/*/examples/tutorials/*.c | xargs sed -i 's/CHKERRQ(ierr);//g' This seems to do the job: http://krupp.iue.tuwien.ac.at/petsc-doxygen/dm_2examples_2tutorials_2ex1_8c-example.html @Jed: I've disabled the EXTRACT_ALL switch, now only documentation for commented entities is generated. Static functions should not be shown anyway (EXTRACT_PRIVATE = NO). I could also set EXCLUDE_PATTERN to something like *_Private and/or *_Internal. Do you know a better systematic way of identifying internal stuff without touching sources? Best regards, Karli > > 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 >
