[petsc-dev] PETSc goes Doxygen!?

Tue Jan 15 16:09:36 CST 2013

On Tue, Jan 15, 2013 at 2:15 PM, Karl Rupp <rupp at mcs.anl.gov> wrote:

> Hi again,
>
> some more improvements to the doxygen generation process have been applied:
>

Right now, the search stinks. If I type in

  GetCone

I get nothing found, whereas

  DMPlexGetCone

has three things found, but does not find DMPlexSetCone. This is crappy,
and will
not replace seeing everything on one page, which I miss.

   Matt

> - 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<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<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<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<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/<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/docs_2doxygen_2examples_2ex1_8c-example.html>
>>>>> http://krupp.iue.tuwien.ac.at/**petsc-doxygen/ex1_8h_**
>>>>> a4204a07ed0f7e0571f0b2b934759b**6b0.htm<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<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
>>>>>
>>>>
>>>>
>>>
>>
>

-- 
What most experimenters take for granted before they begin their
experiments is infinitely more interesting than any results to which their
experiments lead.
-- Norbert Wiener
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130115/7437ea50/attachment.html>