Introduction

Papyrus-Model2Doc is an EMF-based document generator for EMF models. To enhance the user experience compared to existing document generation frameworks, the proposed approach is fully model-based while separating the concerns of (1) how the source model is visited, and (2) what the content of the generated document is. Two EMF models are used to provide the description of these two concerns. A documentation-oriented metamodel allows the document-generator specifier to choose what to generate (titles, tables, lists, images for GMF Diagram, insertion of preexisting file...). The generation is done in two steps. The first one creates an EMF Tree View of the structure of the final document and the second one, is the generation in the expected document format (currently this generator only target the LibreOffice format (odt file), but other output format can easily be developed).

This framework has mainly been developed for EMF, but as it is a subpart of the Papyrus project, several integration are already available:

  1. GMF Diagram
  2. UML
  3. Papyrus
    1. Papyrus integration with Architecture Framework, creation menu, ...
    2. Papyrus GMF Diagram support (Papyrus extends GMF Diagram Framewok)
    3. Papyrus Nattable support

You will get all these parts if you installed all Model2Doc features.

Model2Doc installation

First and foremost, you will need install LibreOffice SDK 6.0 (or upper) on your computer.

The update site for Model2Doc's nightly build is https://hudson.eclipse.org/papyrus/job/Papyrus-Model2Doc/lastSuccessfulBuild/artifact/repository/.

The update site provides the following features:

DocumentStructureTemplate metamodel elements' description

In the document template file:

Children of the TextDocumentTemplate:

Body's description

This element is the most important part of the TextDocumentTemplate file. It defines the contents of the generated document. Here we declare how to parse the model. Basically, we start referencing an EReference (first level) used to get the values from the semantic context of the document, then an EClass (second level), then an EReference again to get the value of the found elements at the previous level, and again EClass, ... Of course others elements are possible, but the goal is to declare a navigation alternating between EReference and EClass.

The generation process will start by taking the semanticContext of the DocumentTemplate and asking it the values of the property represented by the EReference declared in the DocumentTemplate. These values will be consummed by the second level of DocumentTemplate elements to extract relevant ones. Then we take these results and use them as input of the third level which references features too. After this the process will continue by parsing the model using the DocumentTemplate.

  1. First level element
    1. pure EMF
      1. EReferencePartTemplate: to choose which EReference to use. This element can have children
      2. EReferenceTableView: to create a table from a reference value (detail further in the documentation).
      3. TreeListView: to create a list from EStructuralFeature values (detail further in the documentation).
      4. InsertFileTemplate: to declare a path to a file to integrate into the generated document. It won't be a reference, but a copy of its contents into the generated file.
    2. GMF
      1. GMFDiagramView: to define the type of the Diagram owned by the context element to include as image
    3. Papyrus GMF
      1. PapyrusGMFDiagramView: used to import a Papyrus diagram as image. It allows to define:
        • the type of the Diagram to include as image
        • the kindId of the Diagram to include as image (Papyrus Architecture Framework information)
        • a context filtering rules to find diagram by semanticContext (called Root element in the Papyrus interface) or graphicalContext (called owner in the Papyrus interface) (Papyrus integration)
    4. Papyrus NatTable
      1. PapyrusTableView: used to import a Papyrus table. It allows to define:
        • the type of the Table to include
        • the kindId of the Table to include (Papyrus Architecture Framework information)
        • a context filtering rule to find diagram by semanticContext (called Root element in the Papyrus interface) or graphicalContext (called owner in the Papyrus interface) (Papyrus integration)
        • the import method, to import the table as an Image, or as a table in the generated document
    5. UML
      1. StereotypePropertyReferencePartTemplate: to choose a stereotype's property type with a reference to cross the model
      2. CommentAsParagraph: to find owned comment and use their body to create paragraph in the final document
      3. StereotypePropertyReferenceTableView: to create a table from a stereotype's property value (detail further in the documentation).
  2. Second level element
    1. pure EMF
      1. EClassPartTemplate: to reference an EClass, to filter element found in the feature referenced in the previous level
      2. InsertFileTemplate: to declare a path to a file to integrate into the generated document. It won't be a reference, but a copy of its contents into the generated file.
    2. UML
      1. StereotypePartTemplate: to reference a stereotype, to filter the elements found in the feature referenced in the previous level

All the previous elements own these fields too:

On the next snapshot the process to create a new expression.

How to create a TreeListView?

You can create a TreeListView as a child element of the Body of your TextDocumentTemplate itself, or as a child of an EClassPartTemplate or a StereotypePartTemplate. Under a TreeListView, you can create, these elements:

  1. pure EMF
    1. EReferenceListItemTemplate: used to reference an EReference of the context model element of the list. The EReference value will be used to create the items in the document.
    2. EAttributeListItemtemplate: used to reference an EAttribute of the context model element of the list. The EReference value will be used to create the items in the document.
  2. 'UML'
    1. StereotypePropertyReferenceListItemTemplate: used to reference a Stereotype's property typed with a UML element of the context model element of the list. The property's value will be used to create the items in the document.
    2. StereotypePropertyAttributeListItemTemplate: used to reference a Stereotype's property typed with a PrimitiveType of the context model element of the list. The property's value will be used to create the items in the document.

EReferenceListItemTemplate and StereotypePropertyReferenceListItem can have children to create sub items.

  1. pure EMF
    1. EClassListItemTemplate: used to reference an EClass to filter elements referenced by the feature from the previous level and create sub items.
  2. UML
    1. StereotypeListItemTemplate: used to reference a Stereotype to filter elements referenced by the feature from the previous level and create sub items.

How to create an EReferenceTableView or a StereotypePropertyReferenceTableView?

A TableView allows you to display elements of your model with some of their properties' values. Your elements will be displayed as rows : one row representing one element. You can create such TableView as child elements of the Body of your TextDocumentTemplate itself, or as child of an EClassPartTemplate or a StereotypePartTemplate. Once one of these TableView is created, you must fill these fields:

Now that we know how to obtain the rows, we need to declare the column. In order to do that, you need to create new children for your TableView. Possible children are:

  1. pure EMF
    1. EStructuralFeatureColumn: you choose an EStructuralFeature
  2. UML
    1. StereotypePropertyColumn: you choose a stereotype's property

For these 2 elements, you can define your own Column Title. If not, we will use the name of the feature/property.

That's all! The generator will ask the value of the column feature/property for each element represented in row to fill the the cell at the intersection of the row and the column.

How to generate the DocumentStructure from the DocumentTemplate?

Once you finished the configuration of your DocumentTemplate, you can generate your DocumentStructure. in the opened DocumentTemplate editor, Right-Click on the DocumentTemplate, then Generate DocumentStructure.

An input dialog asking you the version of the DocumentStructure to generate opens. You must fill a string value (with char allowed for a file name), then Press Enter. At the end of the process, an dialog will open to inform you about the end of the process. The generated DocumentStructure has been created. This file should be visible in the Project Explorer View.

How to generate the final Document from the DocumentStructure?

Open the generated *.pds file, then select the root element of the file (here, Text Document), then Right-Click-> Generate ODT File. A dialog opens at the end of the process and the generated document appears in the Project Explorer view. (If it does not, you might need to refresh the workspace manually, pressing F5).

How to create a new LibreOffice template?

Here, we will talk about the *.ott file and not about the DocumentTemplate provided by Papyrus-Model2Doc. Of course, we advise you to read the LibreOffice documentation as required. Your LibreOffice template can define styles, header and footer and more generally all features provided by LibreOffice.

The goal of this documentation chapter is to present you the LibreOffice field used by Model2Doc.

To create these custom fields, go in the menu File->Properties->Custom Properties and create them.

To insert them into the LibreOffice template, go into the menu Insert->Fields->More Fields. A dialog opens, go into the tab Variables, select User fields and you can insert these fieds clicking on Insert, as described on the next snapshot.