Antora

Notes about antora and docs.

Generate Command Docs

Command docs can be created using generate-command-docs script. It needs jar option to a fatjar.

docs/generate-command-docs --jar build/libs/spring-cli-0.0.1-SNAPSHOT.jar

• Uses spring-shell feature to template help and help <command> outputs.
• help-commands-adoc.stg simply outputs a list of commands to get documented.
• help-command-adoc.stg outputs asciidoc which we can pipe to antora tree.
• We need fatjar so that it's possible to replace templates using application.properties.
• Everything under docs/modules/ROOT/pages/commands is generated so don't modify those manually and when command set is modified you need to delete content before recreating docs.

We can place additional footer into command adoc by creating a file docs/modules/ROOT/pages/commands/footers/<command>-footer.adoc where command is full command spaces replaced with dashes, i.e mycommand1 sub1 having file name mycommand1-sub1-footer.adoc.

If command structure changes we may have stale files which can be removed. Old files can be removed prior docs generation:

rm docs/modules/ROOT/pages/commands/*adoc