[Insight-users] Re: Doxygen groupings control (fwd)
Luis Ibanez
luis . ibanez at kitware . com
Thu, 19 Jun 2003 09:28:32 -0400
Hi Neil,
ITK uses Doxygen for generating documentation of classes,
but when it comes to application documentation, we are
using Latex.
About your questions:
1) AFAIK, you can not control the depth,
Doxygen displays the whole tree of goups.
What you want may be a good match for PHP.
2) I would suggest you to build an independent
Doxygen tree for each application, and simply
insert relative URLs for common things like
for example a library that is used by both
applications. Doxygen is more oriented to
document a coherent set of classes, rather
than sets of applications.
However, when it comes to document an application
you may have a better deal by simply writing in
LaTeX and generating PDF with hyperlinks, just as
we are doing for the SoftwareGuide.
3) ... again,... if you go with Latex, you
will have better control of the page management.
Note, that when using Doxygen for writing full
manuals, there is a point where you start pushing
Latex inside Doxygen and having to deal with the
additional restrictions of Doxygen itself...
when you reach this point, it simpler to just write
plain Latex. You can always generate HTML and PDF
from the .tex sources anyways.
Doxygen is very good for collecting and organizing
information about classes in a library. It is not
intended to be a generator for full manuals.
"A hammer is not a good screwdriver..."
Regards,
Luis
----------------------
Neil Killeen wrote:
> Luis
>
....
>
> It's all about using Doxygen to document my applications
> as well as my classes (which I think we had a brief
> discussion about). I have asked the doxygen list
> twice but nobody will answer...
>
> Also do you know of the equivalent for VTK to the ITK
> style guide section describing how the libraries
> depend on each other ?
...
>
> cheers
> Neil
>
>
> ---------- Forwarded message ----------
> Date: Tue, 3 Jun 2003 14:25:27 +1000 (EST)
> From: Neil Killeen <Neil . Killeen at atnf . csiro . au>
> To: doxygen-users at lists . sourceforge . net
> Cc: Neil Killeen <nkilleen at atnf . csiro . au>
> Subject: Doxygen groupings control
>
> Hello
>
> I have a few more simple queries about Doxygen, namely to do with
> grouping.
>
> I have a documentation structure
>
> Package 1
> Applications
> App 1
> App 2
> Classes
> Class 1
> Class 2
>
> Package 2
> Applications
> App 1
> App 2
> Classes
> Class 1
> Class 2
>
>
>
> etc. These have been put together with
>
> \defgroup and \ingroup and so this is referred to by the
> modules.html paged that Doxygen creates for me.
>
>
> Question 1
> ----------
>
> How can i control the depth to which ALL of the child sections are shown
> in modules.html
>
> There is in fact more structure below what I have shown (i.e. under
> the actual applications and classes). Therefore,
> I would like to terminate the presented structure at the level
>
> Package 1
> Applications
> Classes
>
> Package 2
> Applications
> Classes
>
>
>
> When the user clicks on, say "Applications" then they are presented
> with
>
> App 1
> App 2
>
>
> Then they click on "App1" etc to be presented with its actual
> documentation etc.
>
> In this way I can keep the main modules.html page to something
> manageable. It will get very large and very deep otherwise.
>
>
> Question 2
> ----------
>
> I am using Doxygen to document my applications as well as my classes etc.
>
>
> So therefore in my structure I'd like to have something like
>
> Package 1
> Applications
> App 1
> General
> Interface
> App 2
> General
> Interface
>
>
> so for each Application I have subsections General and Interface
> which describe how to use the application.
>
> Now, I am trying to figure out how best to do this...
>
> Let us say the group I have defined for the application is called "Package1App1"
>
> I tried writing code as below (ignore the silly words) following examples
> in the \page section of the manual. This code is in a separate file
> called app1.dox that I have asked Doxygen to parse
>
> /**
> * \ingroup Package1App1
> *
> * \page page1 General
> * This is a very nice application
> * See page \ref page2 for the Interface
> */
>
> /**
> * \ingroup Package1App1
> *
> * \page page2 Interface
> * \section sec1 Generic
> * The generic interface is...
> * \section sec2 Specialized
> * The specialized interface is...
> *
> */
>
>
> This works to some degree. Comments and queries are:
>
> I had to put the \page commands in separate /** ... */ blocks or the
> second one didnt work. I.e.
>
> /**
> *
> * \ingroup Package1App1
> *
> * \page page1 General
> * This is a very nice application
> * \page page2 Interface
> * \section sec1 Generic
> */
>
> does not work for the second page.
>
> I didn't get any separate html pages. From the example in \page
> in the manual i was expecting page1 and page2 to have their own linked
> pages. However, they did not. They were all in the one page.
>
> I.e. you see
>
> ------------
> General (small letters)
>
> This is a very nice application See page Interface for the Interface
>
> Interface (small letters)
>
> Generic (large letters)
>
> The generic interface is...
>
> Specialized (large letters)
>
> The specialized interface is...
> ------------
>
> all on the one html page. How do I make them have their own html page ?
> This applies to the \section commands as well which were also on the
> same page. Is this controllable ? It is probably related to Question 1.
>
>
>
>
> Question 3
> ----------
>
> All the pages that I created with the \page command
> also turn up linked to a file called "pages.html"
> (like "modules.html"). Can I prevent some pages (these ones
> in fact) from going there as well ? I only want them in
> one place.
>
>
>
> Question 4
> -----------
>
> Perhaps I have used the wrong commands. Is there something
> else I should be using other than \page etc for this kind
> of generic documentation ? I looked through the list and
> this seemed most appropriate, since \section et al only
> work inside \page
>
>
> many thanks
> Neil
>
>
>
>
>
>
>
>
>
>