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-0001.html>
