Programmatically generate documentation HTML of DMN files for a project

[hanjoosten]

Feature request

The documentation of a .dmn file can be manually downloaded as .html file, by opening the file, go to the documentation tab and press the Download .HTML file button. In my project I have multiple .dmn files, and I would like to programmatically create the documentation in a CI/CD pipeline, so the pages could be served on a site. Is this possible? I would very much like some out-of-the-box feature to generate documentation for all .dmn documents in a project.

[LightGuard]

Until this is implemented, at least for your use case, @hanjoosten, it seems like you could create a Selenium Webdriver test to do all the work in the browser and save the files.

[hanjoosten]

@LightGuard , this could well be, but I never worked with Selenium, so I would have to dig into that, which currently is too much trouble. I might do that in the future at some point though.

[hanjoosten]

If a rewrite is being considered, It might be worthwhile to consider not to do the documentation per .dmn file, but for an entire project. A project contains multiple .dmn files, which are related to each other by includes. In the current implementation a lot that is included is being reported in the .html file of the .dmn file that is being documented. So if there are multiple .dmn files that import the same file, that content of that file is shown in the documentation of multiple .dmn files.

[jomarko]

@hanjoosten thank you for your proposals. Regarding https://github.com/kiegroup/kie-issues/issues/388#issuecomment-1673455266 , what is appropriate solution from your point of view? To reduce documentation length, w should not insert included model documentation, just reference a documentation file name?

[hanjoosten]

@jomarko , it depends on what is feasable. Ideally, I would like a generated one-page website, that contain all definitions that occur in at least one .dmn file in the project. As an example, consider a project with 3 files: a.dmn, b.dmn and c.dmn. a.dmn includes c.dmn and b.dmn includes c.dmn . The definitions in c.dmn should be shown only once. I use this pattern a lot: I have all the data type definitions in a single file, that contain nothing but types. That file is included all over the place. A single project-wide one-pager would also enable abundant use of internal hyperlinks. The main point is to not generate from a single .dmn file, but from the project as a whole.

[tiagobento]

Related to #171. Programatically is harder, since we won't have a browser available to render boxed expressions etc, but we could start from KIE Sandbox.

[awgeorge]

is there anything to generate similar documentation form BPMN2 files?

[tiagobento]

@awgeorge Not currently, unfortunately.