Documentation-Maintainer-Guide.md

how to change flux-commands.md

The entries in flux-commands.md describe the usage of commands used by flux. flux-commands.md is fully automatically generated. To make this happen one has to fill in the proper annotations in the correponding java classes. E.g.

reset-object-batch
------------------
- description:  Resets the downstream modules every batch-size objects
- options:      batchsize (int)
- signature:    Object -> Object
- java class:   org.metafacture.flowcontrol.ObjectBatchResetter

is generated by reading following annotations in ObjectBatchResetter.java:

@Description("Resets the downstream modules every batch-size objects")
@FluxCommand("reset-object-batch")
@In(Object.class)
@Out(Object.class)

The description of "options" is produced from all "public setter-methods", in this case:

 public void setBatchSize(final int batchSize) { ...

The option's name is produced by cutting away the "set" from the methods name, leaving "BatchSize" which is then lowercased. The parameter of this option is generated from the parameter type of the method - here an "int"eger.

how to publish flux-commands.md

If you have updated some of these annotations, say "description", and these changes are merged into the master branch, generate a new flux-commands.md like this:

Go to metafacture-core, checkout master and build a distribution and start flux.sh:

$ ./gradlew installDist
$ cd ./metafacture-runner/build/install/metafacture-core/
$ flux.sh > flux-commands.md

Open the generated flux-commands.md and remove some boilerplate at the beginning of the file manually. Save it, copy it here, commit and push.

The publishing process will be automated with an github action.