Bug 54307 - documentation generation system needed
Summary: documentation generation system needed
Status: RESOLVED FIXED
Alias: None
Product: umbrello
Classification: Applications
Component: general (show other bugs)
Version: 1.1.1
Platform: Compiled Sources Linux
: NOR wishlist
Target Milestone: ---
Assignee: Umbrello Development Group
URL:
Keywords:
: 149791 (view as bug list)
Depends on:
Blocks:
 
Reported: 2003-02-08 20:44 UTC by Richard Turner
Modified: 2007-09-12 07:37 UTC (History)
1 user (show)

See Also:
Latest Commit:
Version Fixed In:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description gael.de.chalendar 2003-02-08 20:44:57 UTC
Version:           1.1.1 (using KDE KDE 3.1)
Installed from:    Compiled From Sources
Compiler:          gcc 3.2.1 
OS:          Linux

After drawing diagrams, the more important feature of an UML modeler is its ability to generate (beautiful) documentation (HTML/PDF/RTF). It comes for me far before code generation (that is never like I like it). But it's a feature absent from all free projects I know...
This should include the possibility to use customized stylesheets to adapt to the look and feel of each company.
Comment 1 Richard Turner 2004-03-17 13:46:28 UTC
I agree and I think this is especially important for use case diagrams - being able to produce a nice document with diagrams and the associated text to present to the users when meeting to discuss use cases is invaluable.  That is, after all, what use case diagrams are for.
Comment 2 Stephan Kulow 2004-05-29 16:34:56 UTC
Replaced gael.de.chalendar@libertysurf.fr with richard@zygous.co.uk due to bounces by reporter
Comment 3 Wolfram Rittmeyer 2004-07-09 12:16:40 UTC
I strongly agree with this one. In fact I think using a modelling tools without the ability to document the models properly for the rest of the team is a rather fruitless operation. I think the most useful aspects of the UML is to be part of the overall documentation - at least until MDA takes off (which I do not believe in for the foreseeable future).
Comment 4 Devon 2004-08-23 23:36:08 UTC
I strongly agree this should be added to Umbrello. This could be accomplished by simply having a template file like a HTML page for documentation and having Umbrello put in the data. For example:
<b>{class_name}</b>:
<list>
{foreach_function}
<li>{function_name}({function_attributes})
<list>
{function_description}
{foreach_attribute}
<li>{attribute_name}: {attribute_description}
</list>
{foreach_attribute_end}
{foreach_function_end}
</list>


could transfer to :
<b>RandomClass</b>:
<list>
<li>RandomFunction(RandomAttr1, RandomAttr2)
<list>
Does random stuff
<li>RandomAttr1: A random attribute
<li>RandomAttr2: another random attribute
</list>
<li>RandomFunction2(RandomAttr1)
<list>
Does more random stuff
<li>RandomAttr1: A random attribute
</list>
</list>

its not the best example but thats the best I could do ;-). Also this could be used to make your own documentation template and do other things too.
Comment 5 Heiko Nardmann 2004-08-24 22:14:47 UTC
Maybe there should be operators navigating on the internal (meta) model. Since there are relationships between the models there should an easy way for the documenter to navigate through the relationships.
Anyone with experiences with GUPRO from university of Koblenz, Germany? They use a model of C (C++ ?) to make it possible to do complex requests to the parsed source code with some kind of SQL-like language.
Such requests could be used to create XML/XHTML files.
Another way to make model serializing having more parameters.
Comment 6 Stefan Seefeld 2004-09-15 02:23:44 UTC
I'd like to add my vote to this feature request. I believe generation of a document could be a simple matter of provide a hook for user defined xslt stylesheets that process the xmi document into some other format (docbook comes to mind !).
In fact, what I would like to see is a general extension mechanism that lets users plug in scripts that can be run on the document (via custom menu items).
But that's something for a different RFE ;-)
Comment 7 Oliver Kellogg 2004-10-11 23:02:51 UTC
Seeing that Qt does not yet natively support XSLT, IMHO
it might be easier to make an external tool that just
reads Umbrello's XMI files.
Some food for thought:

http://www.objectsbydesign.com/projects/xmi_to_html.html
Comment 8 Oliver Kellogg 2004-10-11 23:05:34 UTC
Whoa, I didn't mean to close it
Comment 9 Zeno Gantner 2005-07-20 13:09:06 UTC
This is an important feature.

I think Umbrello should not reinvent the wheel here, but use existing solutions wherever possible.

For class diagrams, it already generates JavaDoc/Doxygen comments,
and the Perl code is documented using the PerlDoc syntax.

It would be nice to be able to call the documentation generator from
within Umbrello.

Maybe it should also allow different Doxygen documentation styles,
although this might be complicated/overkill ...
Comment 10 Oliver Kellogg 2005-07-23 22:37:08 UTC
I adapted the xmi-to-html.xsl from Objects By Design to work with Umbrello 1.4,
save http://uml.sourceforge.net/developers/umbrello-xmi-to-html.xsl to file.
It's still very rough - improvements are welcome.
Comment 11 Gaël de Chalendar (aka Kleag) 2006-06-23 17:06:12 UTC
==== Copy of the mail I just sent to uml-devel ===
Hello,

I just commited the first version of the documentation generator issued from the preexisting xmi-to-html XSLTs. The new File-Export-Export to docbook menu item allows to produce a (still incomplete) documentation in directory named as the xmi file minus its suffix. The diagrams images are generated in the same directory. 
Note that the configure.in.in entries that should check for libxml2 and libxslt do not work. They report a failure bu authorize the compilation when they shouldn't. I need help for that as I am very bad with autotools...

Next step: add an "Export to HTML" menu, that will just do the docbook export followed by a docbook2html conversion using the xslt that will have to be accessible like in the script I presented some days ago.

Comments and corrections are welcome :-)

Enjoy,

Kleag
Comment 12 Oliver Kellogg 2006-09-20 19:19:15 UTC
The documentation generators by Kleag will appear in 1.5.5 in a few days,
thanks again Kleag for your work.
Comment 13 Oliver Kellogg 2007-09-12 07:37:44 UTC
*** Bug 149791 has been marked as a duplicate of this bug. ***