M2DOC command line interface


is there any feasible possibility to invoke m2doc functionality (especially to generate a document using an already existing genconf and template, of course)? If not, is it being planned and for when?


In the context of Capella you can use the command line contributed by @dsryzhov see the issue here. You need to install the the command line feature and then you can run M2Doc generation with:
eclipse.exe -nosplash -consolelog -application org.polarsys.capella.core.commandline.core -appid org.obeonetwork.capella.m2doc.commandline -filepath MCInterfacesModel/genconf/MCInterfacesModel.genconf -data C:/workspace/CapellaCmd -outputfolder /MCInterfacesModel/validation -forceoutputfoldercreation

With new versions of Capella you need to replace eclipse.exe by capella.exe. If you are using Linux or Mac OS it will be ./eclipse or ./capella.

If you are not in the context of Capella, you can use the maven example.

I’ve also created docker image with capella and M2Doc and use it from command line
on the my computer and from gitlab CI to publish documentation from models.
I’ve not created dockerfile yet but simply installed Capella\m2doc manually into docker container.
In some time I plan to create dockerfile .

I also use pandoc (https://pandoc.org/) to generate html from M2Doc generated MSWord
Pandoc also use via docker container

1 Like

Thanks Dmitry, using docker seems to be a good idea how to add a missing CLI to anything, actually. One of the first questions that comes to my mind though is how to actually invoke the m2doc´s “Generate documentation” from within docker container in order to call the container to generate the document.

docker usage is an addition to the way @YvanLussaud described before.
it adds an ability to run m2doc in container on different user machines without the need to install additional software.

So start from running m2doc from CLI on your machine. After success procede to creating docker container and use it.

To use this command you need to create Capella workspace, add your Capella project with genconf. When running eclipse.exe from command line you will need to set -filepath and -data parameter to your paths.

After you will install Capella and m2doc into docker container
you can pack command that run eclipse in container into some sh file in the docker container and execute it from host machine using
docker run … /bin/bash -C “runm2doc.sh”

runm2doc.sh content
eclipse -nosplash -consolelog -application org.polarsys.capella.core.commandline.core -appid org.obeonetwork.capella.m2doc.commandline -filepath <workspace_relative_path_to_genconf> -data -outputfolder -forceoutputfoldercreation

you can also pack “docker run” command into runm2doc.bat file (in windows) and use it to run m2doc

As I said before I had a plan to create docker container and write detailed instrunction how to write it. I will try to do it in the near future.
What version of Capella do you use?

Thanks, we´ll try it out (sorry, I missed out on the previous answer of Yvan, somehow).

I have been trying the command line feature with the following command line:
eclipse.exe -nosplash -consolelog -application org.polarsys.capella.core.commandline.core -appid org.obeonetwork.capella.m2doc.commandline -filepath TestM2Doc/template.genconf -data “C:/Users/T0161897/Application Data/Orchestra/MelodyTeam/workspace” -outputfolder /TestM2Doc -forceoutputfoldercreation

And get this error message:
java.lang.IllegalArgumentException: Path must include project and resource name: /TestM2Doc

I am not sure what i wrong here. What exactly are the areguments -data, -filepath, -outputfolder ? Is there any documentation?

All files (template, genconf) are in the project directory ‘…\workspace\TestM2Doc’. Generation works via GUI.

Here is an extract from the logfile:
!SESSION 2021-02-08 16:19:22.519 -----------------------------------------------
java.vendor=Oracle Corporation
BootLoader constants: OS=win32, ARCH=x86_64, WS=win32, NL=en
Framework arguments: -pluginCustomization pluginCustomization.ini -application org.polarsys.capella.core.commandline.core -appid org.obeonetwork.capella.m2doc.commandline -filepath TestM2Doc/template.genconf -outputfolder /TestM2Doc -forceoutputfoldercreation
Command-line arguments: -os win32 -ws win32 -arch x86_64 -pluginCustomization pluginCustomization.ini -consolelog -application org.polarsys.capella.core.commandline.core -appid org.obeonetwork.capella.m2doc.commandline -filepath TestM2Doc/template.genconf -data C:/Users/T0161897/Application Data/Orchestra/MelodyTeam/workspace -outputfolder /TestM2Doc -forceoutputfoldercreation

java.lang.IllegalArgumentException: Path must include project and resource name: /TestM2Doc

OK, I found the cause.

Obviously, you have to add a subdirectory to -outputfolder. With ‘-outputfolder /TestM2Doc/validation’ the generation from command line does work.

Still, it is not clear to my why you have to add a subdirectory.

It looks like a bug to me. I think I fixed something similar in the core of M2Doc. Can you report the problem here ?

If I run m2doc from commandline and there are application errors in the execution, I get an error message window, which I have to confirm by pressing the OK button.
For automated execution this does not work.


In the logfile I have an application error:
!ENTRY org.eclipse.osgi 4 0 2021-04-14 12:25:05.915
!MESSAGE Application error
at org.obeonetwork.capella.m2doc.commandline.M2DocCommandLine.execute(M2DocCommandLine.java:120)

Is there any possibility to suppress these windows?

This is the command line:
Command-line arguments: -os win32 -ws win32 -arch x86_64 -pluginCustomization pluginCustomization.ini -consolelog -application org.polarsys.capella.core.commandline.core -appid org.obeonetwork.capella.m2doc.commandline -filepath ATO-OB_Core/m2docTemplates/ADD.template.genconf -data \thsdiza06fs01\orchestra_data$\Projects\ATX\artefacts\Melody -forceoutputfoldercreation

Document generation works fine in headless mode, if there are no appication errors.

I think the filepath argument might be bogus. You should try to only use slashes and also add the genconf file as the last segment. Still the NPE is a bit overkill… can you open a bug here please, make sure to include the stack trace.

The command line works fine, if the document generation runs without error.

Only if the document generation is producing an error (for whatever reason), I get an error message window during execution. The problem is that the job then doesn’t run to the end, because in headless mode there is noone to press the window’s ‘OK’ button.

So, my point is how I can get it run in real headless mode under all conditions.

OK I understand. I think for that the code need to be modified. I will have a look at this problem. I opened the following issue:

Thanks :slight_smile:

I was not able to reproduce with my current dev environment has commented in the issue. Can you comment on the issue with your versions of M2Doc M2doc extensions for Capella (optional) and your version of Capella please. Maybe something else was triggering the GUI. Also if you have some error logs related to this issue, it could be interesting.

I am still struggeling in some cases to get the command line run.

I have attached 2 logfiles commandline-BAD and …GOOD.
The only difference is that it is two different projects. In both cases the generation runs from GUI. But, the BAD case doesn’t run from command line. And I have no idea why …? In both cases the templates are trivial, newly created without any adaption.

m2doc-commandline-BAD.txt (3.7 KB) m2doc-commandline-GOOD.txt (4.4 KB)

In the bad case there is a stack trace, but nothing else to give a hint:
The command-line launcher to generate .docx from your models.

!ENTRY org.eclipse.osgi 4 0 2021-04-26 16:51:02.165
!MESSAGE Application error
at org.obeonetwork.capella.m2doc.commandline.M2DocCommandLine.execute(M2DocCommandLine.java:120)
at org.polarsys.capella.core.commandline.core.CommandLineApp.launchApp(CommandLineApp.java:138)

Maybe, the stack trace tells you something.


This exception is related to the provided .genconf URI. I think it’s when the genconf file is invalid. I opened a bug: