[petsc-dev] PETSc goes Doxygen!?

[Jed Brown]

Can we also hide all the internal stuff?
On Jan 12, 2013 6:21 PM, "Barry Smith" <bsmith at mcs.anl.gov> wrote:

>
>   Not bad.
>
>   Any way to strip the ierr = and CHKERRQ(ierr); from all the html
> versions of the source code. I find it cluttering and ugly.
>
>    Barry
>
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130112/68e6e152/attachment.html>