document generation with m2doc - eclipsecon france2018€¦ · o is y d t be d ut r n nt 7 document...
TRANSCRIPT
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
1
Document Generation with
M2DocYvan Lussaud
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
2
Why documents?
• Written Documents are still necessary
– Transmit information to people who will not use the modeling workbench directly
– Fulfil certain obligations
• The Model should be the reference
– Up to date documentation
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
3
Actors Involved
CASID/DGSIC (French Department of Defense)
© Alexander W. Galbraith - This image is available from the City of Toronto Archives, listed under the archival citation Fonds 1568, Item 177.
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
4
Our Solution
M2Doc
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
5
Our Solution
Model to documentation
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
6
Basic Principles
M2Doc
Template
Model
Document
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
7
Document
Basic Principles
M2Doc
Template
ModelModel
Document
A380Technical specifications –DDE-H35Applicable DocumentsLorem ipsum dolor sit amet
Lorem ipsum dolor sit ametLorem ipsumdolor sit ametlorem ipsumdolor sit ametdolorem ipsum dolor sit am
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
8
Document
A380Technical specifications –DDE-H35Applicable DocumentsLorem ipsum dolor sit amet
Lorem ipsum dolor sit ametLorem ipsumdolor sit ametlorem ipsumdolor sit ametdolorem ipsum dolor sit am
Basic Principles
M2Doc
Template
Model
Template B
Template C
Document B
A380General Overview –DDE-H35Applicable DocumentsLorem ipsum dolor sit amet
Document C
A380Structure Breakdown –DDE-H35Applicable Documentsipsum dolor sit amet meae quam
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
9
Roles Involved
Metamodel Expert
• Creates, tests and debugs reusable AQL services
• Registers services
Templatist
• Creates M2Doc templates
• Uses AQL services• Tests and debugs
templates
End-User
• Edit models• Produces documents
by running M2Doc templates
• Edit ‘userdoc’ in generated documents
These are just roles
Can be 1, 2, or 3 personsdepending on complexity and organization
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
10
Writing Templates
• Plain MS Word™ document (.docx files)
• Use Alt+F9 to activate fields
• Use Ctrl+F9 to insert fields
• M2Doc syntax is very simple
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
11
{ m:xxx … }
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
12
Simple query
{ m:conf.name } is located in Ludwisburg
EclipseCon Europe is located in Ludwigsburg
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
13
Loop
{ m:for track | conf.tracks}
• Track: {m:track.name}
{ m:endfor }
• Track: IoT Day
• Track: Eclipse Technologies
• Track: OSGi
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
14
Loop
{ m:for track | conf.tracks}
{ m:endfor }
{m:track.name} {m:track.description}
IoT Day Internet of Things
Eclipse Technologies Eclipse-related technologies and eclipsecommunity
OSGi Talks about OSGi
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
15
Conditional
{ m:if conf.name.contains(‘Eclipse’) }
…
{ m:else if …}
…
{ m:else }
…
{ m:endif }
Optional
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
16
User Doc
{m:userdoc <queryID>}
…
{m:enduserdoc}
• Incremental generation
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
17
Bookmark and link
{m:bookmark <queryID>}
…
{m:endbookmark}
{m:link <queryID> <queryText>}
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
18
Let
{m:let cName = conf.name}
…
{ m:cName } is located in Ludwisburg
…
{m:endlet}
• Define variables
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
19
Using Services
{m:if
conf.tracks.talks
−>select(t|t.name.contains(‘Sirius’))
−>notEmpty()}
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
20
Using Services
{ m:if conf.hasTalkAbout(‘Sirius’) }
public boolean hasTalkAbout(Conference, String)
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
21
Using Services
• Services are Java methods
• Facilitate creation and maintenance of templates
• Can be reused
• Can insert images/tables/formated text/…
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
22
Validation
{ m:conf. } is located in Ludwisburg
{ m:conf. } <---Expression “conf." is invalid: missing feature access or service call is locatedin Ludwisburg
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
23
M2Doc + Sirius = ♥
• Diagrams and Tables can be inserted
• The existence of a diagram/table can bechecked
– Dedicated services are provided
• isRepresentation(DescriptionName)
• asImageByRepresentation(DescriptionName)
• asTableByRepresentation(DescriptionName)
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
24
M2DOCDEMO
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
25
Architecture Overview
AQL Apache POI EMF
M2Doc coreSirius
M2Doc IDE
M2Doc UI
M2Doc Sirius Integration
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
26
Architecture Overview
AQL Apache POI EMF
M2Doc coreYour product
M2Doc IDE
M2Doc UIM2Doc your product
Integration
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
27
Show me the code!
https://github.com/ObeoNetwork/M2Doc/
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
28
M2Doc – Roadmap
• V1.0.0 has been released
– First maintained version
– Fully documented
• Next
– Gather feedback
– Keep improving + features from feedback
– Improve Apache POI integration
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
29
Keypoints
• Produces MS Word™ documents fromEMF-compliant Models
• Can include Sirius Diagrams & Tables
• Easy to use: simple syntax, tooling helps
• Has Useful Error Reporting
• Supports Incremental Generation
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
30
© c
op
yrig
ht
20
17
Ob
eoTh
is do
cum
ent is
the p
rop
ertyo
f Ob
eo an
d can
no
tb
etran
smitted
with
ou
tp
rior
written
agreemen
t
31