[petsc-dev] PETSc goes Doxygen!?

[Karl Rupp]

Hi again,

some more improvements to the doxygen generation process have been applied:

- Examples are finally filtered now as I specified everything correctly 
(not a Doxygen shortcoming, bug report closed).


 >     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

The listing of
http://krupp.iue.tuwien.ac.at/petsc-doxygen/ksp_2ksp_2examples_2tutorials_2ex4_8c-example.html
is now identical with the one Barry mentioned - except for a violation 
of coding style on lines 49/50 that already affects the sources. I'll 
send a separate email on that.

- Examples now carry correct line numbers even with things stripped out. 
This required a small Doxygen patch, which I've sent to the developers 
for inclusion in the next release.

- Private functions no longer show up in the various modules (this was 
caused by /*MC incorrectly being interpreted as part of a function 
documentation)

There are still a bunch of private data structures shown. There is no 
consistent way of determining whether a data structure is private or 
not. The underscore could be a criterion, but then it misses some rather 
important things such as DM_Plex:
http://krupp.iue.tuwien.ac.at/petsc-doxygen/structDM__Plex.html
(Note that I could further improve the data field documentation if I 
were allowed to touch sources and replace /* ... */ by /** ... */)

Has there already been a decision made on whether the Doxygen 
documentation should be kept for the future (irrespective of whether 
this has any influence on the use of sowing)?

Best regards,
Karli



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