[DISCUSS] An idea for how we can have our driver documentation partially updated automatically

[chrisdutz]

Hi all,

I know one major problem we are having, is that the documentaiton for our drivers is usually quite out-dated.
While working on the UI tool, I am refactoring some parts of the PLC4J api to make a lot of information available to an automated editor.

Now this got me thinking ... I could probably use the same technique in the build to automatically generate adoc documents as part of the build. This way we could automatically document which parameters a driver provides, if they are required or not, what type they have etc.

I would propose to generate some meta-adoc files, which we then could simply import from the normal documentation ... this way we can still provide awesome text, like cesar's S7 documentation, but the table at the top, would automaticaly be updated with the state of PLC4J drivers.

Do you think something like this would make sense?

[sruehl]

Yeah I really like they idea. This way the adjustments to the doc are right at your hands. Big plus from my side

[sruehl]

althought I would not restrict it to PLC4J, I would do it as tab view or whatever to select the current language. (there was an example I had in mind on this site https://docs.datadoghq.com/logs/log_collection/?tab=host#setup but I can' find one for languages, but the tabs there are quite nice to select information which is relevant for you)

[chrisdutz]

Well the reason I was talking about PLC4J is that the build is in Java and therefore I can use PLC4J to inspect the features of the drivers. I wasn't planning on parsing the config files, but more having a module where groovy for examples uses the Plc4j driver manager to iterate over all drivers and then to dump their config option.