Binding documentation generator

[sjsf]

migrated from Bugzilla #476081
status NEW severity enhancement in component Binding for ---
Reported in version unspecified on platform All
Assigned to: Project Inbox

On 2015-08-27 19:49:18 -0400, Alexander Kammerer wrote:

Hey everyone,

I've written a Maven Mojo that makes it easy to generate documentation for a binding based on the XML configuration.

You can find it here: https://github.com/kummerer94/binding-docu-generator

I am parsing the available XML configuration and used the README.md template from the binding archetype as a base. I use Mustache to generate the markdown files.

(Read more in this issue: openhab/openhab-addons#348)

Here is an example: https://github.com/kummerer94/binding-docu-generator/blob/master/generated-docu-mustache.md

I would really appreciate some feedback.

Regards
Alexander

On 2015-09-08 16:28:35 -0400, Dennis Nobel wrote:

Hi Alexander,

sorry for late feedback. But now I had the time to look into your generator.

As already written in the openHAB2 issue, we really like the solution and it would be good have such generator within Eclipse SmartHome. So thanks again for the great work.

Just a few questions:

• You have setup the tool as an own project. Do you plan to contribute it to the official Eclipse SmartHome project or do you want to keep it as separate project?
• In the openHAB2 issue you have written, that the XMLs are not automatically found. This is fixed, right?
• How does the generation process work? Do I need to start the maven mojo within my binding? Will the generated markdown file be checked in as part of the binding or can it be automatically generated for the documentation?

If you want to contribute it to ESH, you first have to change the namespace into org.eclipse.smarthome. You also need to create a fork of the ESH repo and put the tool into the "tools" folder. Next step would be to integrate it into the build.

We should also automate the process of generating the JAXB schema classes within the build and fetch the XSD files from the other ESH bundles, to not maintain two copies of the same schema.

Regards

Dennis

On 2015-09-10 16:08:09 -0400, Alexander Kammerer wrote:

Hey Dennis,

thanks for your feedback!

• You have setup the tool as an own project. Do you plan to contribute it to
  the official Eclipse SmartHome project or do you want to keep it as separate
  project?

I think it would be best to integrate it into the Eclipse SmartHome project as it is all about it. I will follow your description. Thanks! - This leads us to the next thing:

• In the openHAB2 issue you have written, that the XMLs are not
  automatically found. This is fixed, right?

The XMLs are now automatically found and parsed. You only need to provide the plugin with the right path (defaults to ESH-INF/).

• How does the generation process work? Do I need to start the maven mojo
  within my binding? Will the generated markdown file be checked in as part of
  the binding or can it be automatically generated for the documentation?
  At the moment the generation of the markdown is not ready to be integrated into the build process. The current version is thought to be run once and then integrated by yourself into your markdown file via copy paste.

Of course, it makes sense to integrate the generation process into the build. For that to work, there are several changes needed.

You must be able to give the plugin a simple template file where you write down your other documentation and use placeholders for the generated parts. The plugin then generates the documentation and creates a file in the directory.

I will rewrite the affected parts.

We should also automate the process of generating the JAXB schema classes
within the build and fetch the XSD files from the other ESH bundles, to not
maintain two copies of the same schema.
This is possible but seemed buggy at the time I was creating the JAXB schema classes. I will work something out.

It may take some time until I have implemented the changes. After I'm done I will fork the Eclipse Smarthome repository and create a pull request.

Regards
Alexander