doxygen-users

[Doxygen-users] Can doxygen do this (including not only examples, but also their output )?

[Stephan P. <ste...@gm...>]

Hi everyone,

I'm new to doxygen and I'm currently trying to figure out whether it's
the right tool for the job. I believe it is, since I've done a few
tests, but before I run into a time-consuming dead end I just wanted to
ask if anybody can tell me weather certain things are indeed possible.

The "job" is the manual for a code library (from the area of
thermochemistry, if anyone cares to know :-) ), and it does NOT involve
documenting the source code of the library itself. Actually, it doesn't
even matter in which language the library is coded (it's Fortran), since
doxygen doesn't need to touch this code.

The key components of the documentation are:

- Free flowing text with tables, graphics, lists, links, etc. (no
problem for doxygen, although I did have to improvise a little already
in my tests :-) )

- short (but complete) example programs that illustrate the use of all
the functions the library provides, currently in C and Fortran, but
potentially later also in Pascal/Python/Java.

The latter is where I'm currently not 100% sure whether and how it can
be done with doxygen, since what I would like to do looks like this:

http://gtt.mch.rwth-aachen.de/gtt-web/Software/ChemApp/CAL-DOC/cal62.html#l100

(This is btw. an older version of the documentation which I started in
the late 90s, I used "Yodl" for this, plus a number of custom Perl
scripts run via Makefiles for pre- and postprocessing. But I'd like to
move away from Yodl to a more "active" tool with a larger user base...)

You can see that I splice chunks of output of the very sample programs
into the documented code. In fact, the output is generated from the
current version of the library automatically right before the
documentation is made.

Some example programs write the calculated results to output files that
I process with gnuplot into images and again insert back into the
documented code:

http://gtt.mch.rwth-aachen.de/gtt-web/Software/ChemApp/CAL-DOC/cal81.html#l122

Another important detail is that all calls to the library's few dozen
subroutines are all cross-linked. This is normally not a problem for
doxygen, but in my case I am *not* scanning the source code of the
library, and using \fn instead does not seem to the trick yet.

I did have a look at \dontinclude and related commands, but out of the
box none of them quite seem to fit my bill...

Does anybody out there use doxygen in such a way? Is that possible? One
way or the other I'm sure it is, but I'd like to get a feeling for how
easy or tricky it is, in order to judge how big a project the conversion
from Yodl to doxygen would be.

Thanks in advance for any pointers,

Stephan

Re: [Doxygen-users] Can doxygen do this (including not only examples, but also their output )?

[Scott F. <sco...@gm...>]

On 19/05/14 08:17 AM, Stephan Petersen wrote:
> Free flowing text with tables, graphics, lists, links, etc. (no
> problem for doxygen, although I did have to improvise a little already
> in my tests:-)  )
Have you looked at other options such as latex or 
docbook(http://www.docbook.org/)?
If the code isn't the issue, maybe another documentation language would 
be useful?
Just a suggestion.

Re: [Doxygen-users] Can doxygen do this (including not only examples, but also their output )?

[Stephan P. <ste...@gm...>]

Hi Scott,

thanks a lot for your quick reply.

> Have you looked at other options such as latex or 
> docbook(http://www.docbook.org/)?
> If the code isn't the issue, maybe another documentation language would 
> be useful?

Actually, I had decided to take a closer look at doxygen and Docbook.
Since Docbook and the necessary tool chain looked a bit daunting, I
decided to give doxygen a try first :-). But since I would not really be
using it for what it was primarily intended (at least for this project),
it could be doxygen is not the optimal tool...

All the best,

Stephan

Re: [Doxygen-users] Can doxygen do this (including not only examples, but also their output )?

[Barnes, P. D. <bar...@ll...>]

Hello Stephan,

We[1] use a combination of doxygen (for API) and Sphinx[2] for more expository docs, such as tutorial and manual.  In particular, it's straightforward Sphinx to integrate portions of an example program along with the output.  Sphinx uses make to generate the documentation, so it's also straightforward to build and run the example code as part of building the documentation.

Peter

[1]  https://www.nsnam.org/docs/release/3.19/tutorial/html/index.html
https://www.nsnam.org/docs/release/3.19/manual/html/index.html

[2]  http://sphinx-doc.org

On May 19, 2014, at 7:17 AM, Stephan Petersen <ste...@gm...> wrote:
> I'm new to doxygen and I'm currently trying to figure out whether it's
> the right tool for the job.
> - short (but complete) example programs that illustrate the use of all
> the functions the library provides, currently in C and Fortran, but
> potentially later also in Pascal/Python/Java.
> 
> The latter is where I'm currently not 100% sure whether and how it can
> be done with doxygen, since what I would like to do looks like this:
> 
> http://gtt.mch.rwth-aachen.de/gtt-web/Software/ChemApp/CAL-DOC/cal62.html#l100
> 
> Stephan

_______________________________________________________________________
Dr. Peter D. Barnes, Jr.                Physics Division
Lawrence Livermore National Laboratory  Physical and Life Sciences
7000 East Avenue, L-50                  email:  pdb...@ll...
P. O. Box 808                           Voice:  (925) 422-3384
Livermore, California 94550             Fax:    (925) 423-3371

Re: [Doxygen-users] Can doxygen do this (including not only examples, but also their output )?

[Stephan P. <ste...@gm...>]

Hi Peter,

> We[1] use a combination of doxygen (for API) and Sphinx[2] for more
> expository docs, such as tutorial and manual. 

thanks for pointing out Sphinx, I had not heard of it until now.

> In particular, it's
> straightforward Sphinx to integrate portions of an example program
> along with the output.  Sphinx uses make to generate the
> documentation, so it's also straightforward to build and run the
> example code as part of building the documentation.

Sounds good. When you make changes to example programs which changes
their output, then rerun your make-based documentation creation process,
is the changed output automatically reflected in the docs?

The way I do it in my old Yodl-based documentation is that an example
program has for instance the line
printf("###include###\n");
at the position where a chunk of output should be displayed. A Perl
script would then take the source code and the program's output and
replace the printf("###include###\n") lines with the chunks of output.
Is your Sphinx-based system similar? I'm just trying get a head start on
understanding which features of Sphinx I need to look at to judge how
this could be done.

Thanks and all the best,

Stephan