feature(asciidoc): New maven-plugin for extracting UI tooltips from asciidoc source

[rhuss]

See https://github.com/syndesisio/syndesis-project/issues/47 for the initial discussion.

The idea is, to create a Maven plugin which:

• Looks into an Asciidoc file, where tooltip are defined in a certain way (kind of key-value pairs). This should be part of the regular documentation, the tooltips themselves should be marked by some asciidoc means or via doc conventions.
• Creates a 'syndesis-tooltips.json' file which can be consumed directly by the UI
• This file needs to be checked into Git and pushed to GitHub
• The syndesis-ui build process downloads this file directly from GitHub (possibly with tags information).

The suggestion is to leave the plugin in this repo, where it is used.

[TovaCohen]

@gashcrumb and @kahboom , I just want to make sure you are aware of this issue. I am wondering (hoping!) if guided tour content can be pulled from asciidoc source files that @nichmoore and I create.

[gashcrumb]

Yeah, pulling the content for the tooltips from the documentation would be ideal for sure...

[kahboom]

@rhuss - Didn't @fbolton mention that we already have a plugin like this on this issue https://github.com/syndesisio/syndesis-project/issues/47#issuecomment-322598613 ? I could be missing something though.

[fbolton]

@kahboom, we use the Maven Asciidoctor plug-in to build our doc, but that's not directly related to the tooltips. For the tooltips there exists a Python script written by Ernie Allen (from the enMasse project). I think @rhuss was implying we could re-implement the Python script as a Maven plugin.

[rhuss]

Actually, I would like to implement this as a maven plugin which should be not that hard. Actually what would be needed to start is

• Definition of the input format, i.e. the conventions used within the asciidoc
• Definition of the output JSON

If someone could provide some pointer to this information so that we don't have to reverse engineer the python script, this would be awesome.

[TovaCohen]

@fbolton is on PTO till September 7. I'll paste his comment in the related issue (https://github.com/syndesisio/syndesis-project/issues/47) below. Maybe those links provide the information you are looking for:

From Fintan: In a recent conversation with the "Messaging as a Service" docs team (the EnMasse project), we discovered that they already have a tool for extracting UI labels and tooltips from their Asciidoc documentation. One of the EnMasse developers, Ernie Allen, created a script to extract content from Asciidoc source, producing a JSon file as output:

https://github.com/ErnieAllen/routilities/blob/tooltips/parse.py

And here is a sample of an Asciidoc file that works with this tooltip extractor script:

https://raw.githubusercontent.com/ErnieAllen/routilities/tooltips/model.adoc

[lburgazzoli]

@rhuss I can work on this plugin, should we "port" the python script to maven as it is or is there anything else to take into account ?

[rhuss]

Thanks a lot !

I think we should just port it, as the main concern was to have no python dependency in the build. Not sure about the format (we can improve it for sure if we need to), but the idea is, that the plugin runs in this repo, generate json file(s), these get checked in then.

Then from the UI build, the files are downloaded from gitub via raw.github.com, and put into the assests for the ui client so that its deployed along with syndesis-ui.

[kahboom]

Thank you @lburgazzoli , that would be a huge help! 👍

[lburgazzoli]

@rhuss @kahboom can anyone assign the issue to me ? Or I'll forget

[lburgazzoli]

@rhuss

I've created a plugin which is a raw port of the python script on my GitHub account:

https://github.com/lburgazzoli/syndesis-documentation-maven-plugin

When executed the mojot generates the same json as the python one.

• Can anyone have a look and check if it is ok ?
• The artifact is syndesis-documentation-maven-plugin , if you have any better name ...
• Should the plugin be contributed here or somewhere else and used here as part of the build ?

[rhuss]

@lburgazzoli haven't checked the implementation yet, but it looks clean and simple. The name is perfectly fine and I would commit it to this repo. Just ask @fbolton how to best include it into the build process.

Next step would be to agree on a location where to commit this generated json and adapt the syndesis-ui build to fetch the json during build time.

[fbolton]

@lburgazzoli and @rhuss, sorry for the slow response - just back from vacation.

So, presumably, the sort of workflow you are talking about would be to run the new Maven plug-in in the syndesis-documentation repo, commit the resulting json file into the a well-known location in the syndesis-documentation repo, and let syndesis-ui pick it up at build time. But this is still rather vague. Perhaps we should have a quick meeting to thrash out the details?

[lburgazzoli]

Should we close this as it has been merged ? We may open a new issue for workflow integration.

[gashcrumb]

Absolutely, be good if the next issue maybe just links back to this one

[lburgazzoli]

So @rhuss @fbolton or you can close it, I do not have the permissions :)

[gashcrumb]

We should fix that :-)