M2Doc, Description with diagram

Document Generation
1

Hello all,

I just started a new document, and I’m happy to tell you that I can show diagrams by calling (for instance)

self.eAllContents().representationByDescriptionName('Operational Capabilities Blank').asImage().setWidth(400)

So far so good. But I’d really like to quickly start my documentation by adding the “description” I already wrote in my Cappella model. Graphically:

image
image1232×942 152 KB

So I thought I must be able to do this, but this returns null…

self.eAllContents().representationByDescriptionName('Operational Capabilities Blank').description

:question: My questions: :question:

In order of importance:

  1. Can I get the description I typed in Capella by first finding the diagram and then looking for its description?
  2. And how could I have found that without asking you? I have a bit trouble of finding my way around what data lives where… I’m using Capella 5.2.0 with M2Doc 3.2.1
  3. Why does nobody seem to want to do it this way :thinking: ?

Thanks :pray: in advance!

2

  1. Yes, but the description is not stored on the DRepresentation, it seems to be stored in its DRepresentationDescriptor:

    {m:myRepresentation.getDescriptor().documentation}

You will probably want to convert the HTML and maybe replace the links to bookmarks in your document. You can add:

{m:myRepresentation.getDescriptor().documentation.fromHTMLBodyString().replaceLink(myRepresentation)}

  1. I changed the description and saved the model. Then I opened the changed file (.aird) and search for the changed text. Also the screen shot shows “(DRepresentation Descriptor)” which helped me a bit. An other tool is the M2Doc interpreter view. It allows to write AQL expression in the context of your template and has a similar rendering as in the generated document. It provides content assist using CTRL+SPACE.

  2. The SA template from the M2Doc IFE sample project shows how to extract the description of a CapellaElement. The conversion from HTML to docx has also been improved in the last version of M2Doc (3.2.1), so I think people seems to use it. And in general it’s a good way of documenting elements because this way you can reuse the documentation for other kind of exports and not only in documents generated with M2Doc.

1 Like
3

Thanks so much for the reply! The solution to do a diff with the .aird is quite surprising and an unexpected but perfectly working approach :slight_smile:

I already looked through the SA template and te LA template, but those iterate mostly over functions and elements that make up the model, but not descriptions of the diagrams themselves(yes, descriptions which give the “kind” of diagram, but not “description” which is the text entered in “description” in Capella). To me that seems odd, as I think a good diagram will probably benefit from some text to explain its scope and purpose.

As a side note: this probably explains why the generated SA documentation does read a bit like auto-generated doxygen, describing all parts, but not the whole. Maybe adding a bit of diagram descriptor.documentation could help.

Anyway, thanks a million for the “solution” :jigsaw: :+1: . I’m happy because I can share more (consistent) info with my team!