[petsc-dev] PETSc goes Doxygen!?

[Barry Smith]

   You can also take out the   PetscErrorCode   ierr;  since ierr is never used.

    Note that your change now changes the line numbers because it removes some lines, thus the lines do not match up with the C code. In our current way of processing we list the line numbers on the left side: http://www.mcs.anl.gov/petsc/petsc-current/src/ksp/ksp/examples/tutorials/ex4.c.html

   Barry

On Jan 13, 2013, at 5:30 PM, Karl Rupp <rupp at mcs.anl.gov> wrote:

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