Plugin interface for documentation generation intercept

[Krzysztof Swiatkowski]

One of the things that are both good and not good enough is the documentation.
Given different needs of people I don't think Sparxians will ever be able to create document generator that will allways suit everyone.
I think it would be great to have some kind of interceptor interface to allow those who are interested to intercept parts of the documentation and do the filtering/updating/whatever they need. This way I would not be required to write my own document generator just to do few simple things that are not possible now.

Kris
PS. Correct me if I'm wrong but I have not found such interface in current EA API.

[«Midnight»]

You are correct Kris, there is no "interceptor" in the API. This is one of the areas that are 'closed' to automation. Others are XML and XMI manipulation, and DDL generation and import.

That doesn't mean you cannot build your own documentation system through the API. Many of us - myself included - have done so. But you have to do it from the ground up, and you are at the mercy of internal changes to the product.

By all means, please pursue this with Sparx. Submit a 'formal' feature request, since these get direct attention (whether or not they get action). You'll find the appropriate form by clicking the Feature Request link below the Support link near the bottom of any forum page.

Please post back and let us know what, if anything, Sparx has to say on the matter.

David

[thomas.kilian]

FWIW: I create all my documentation using the API (why use 3 different technologies if I could deploy a single one). The only secret: how to create the real documentation. You can use RTF (Rip That F...), HTML (probably not so beautiful) or TeX (maybe there are more alternatives).

[Geert Bellekens]

Same here. To create decent documentation you need your own addin where you can tweak things exactly to your needs. (By decent I mean: documents that look like they have been written by hand)
In creating such a tool I found myself writing a whole lot of "framework-code" that could have been supplied by Sparx.
In my case that framework included
- Outputting things to MS Word (text, tables, matrices, diagrams, RFT fragments)
- Translating (I used an excel sheet to store translations and translated each text element before outputting it to my document)
- Selecting elements from the repository: I had a bunch of operations like "GetClassesOnDiagram", "GetUsecasesInPackage" etc...

Once the majority of the framework was finished, creating a new template was a matter of hours.

So absolutely you have my vote!

[Dermot]

Hello Kris,
As a add-on to the replies above, there is actualy code available on the Web site for an interface between EA and MS Word.  This was writtern back in 2004 in VB for the VBA of Word.
The code is availabe from:
http://www.sparxsystems.com/resources/developers/autint.html

[Krzysztof Swiatkowski]

Hi Dermot,

I know there is possibility of calling EA automation interface and building my own report generator, I've been there.
But that is not what I was suggesting here.
There are times when I could get things done simply by intercepting what EA does. So may proposal was actually like this:
EA Generates document ->
foreach( element in docElements )
  if there is interceptor
     call Interceptor
     react on result - whether to include or exclude element or put new changed text in a document or whatever would be possible
  else
     do standard EA stuff
end

This way I could modify what EA does without going into writing my own generator. I don't have the time to write very general one with templates so I end up modifying specific code for specific customers.