[petsc-dev] PETSc goes Doxygen!?

[Karl Rupp]

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
>