Support variable substitution for doc example code

[pvlugter]

Something like example build files for documentation will often want to substitute current version variables from the project build. Paradox vars are not replaced for included snippets, and we probably want to first substitute variables and test the example, then pull into the docs via snippets. What we've done in other projects is build simple substitution/templating steps into the build for this. Also see discussion.

[rstento]

Antora supports this out of the box. For the cloudstate machine docs, I've set up a file to keep variable definitions all in the same place, see https://github.com/lightbend/cloudstate-docs/blob/master/docs/modules/ROOT/partials/include.adoc. I also have added variables that are in PR #62 for :minimum_kubectl_version: 1.17.0 :minimum_protoc_version: 3.0.0 :minimum_docker_version: 19.03

I am also adding to the readme to remind contributors where to update these values.

[pvlugter]

We're aiming for something a little different in this case: not just variable substitution in the docs, but in code that first has the substitutions, and is then built, compiled, tested, and then is just a regular snippet include for the docs. Having these examples tested is much easier for maintaining the docs.

[rstento]

Got it, thanks!

On Wed, Jun 3, 2020 at 4:45 PM Peter Vlugter [email protected] wrote:

We're aiming for something a little different in this case: not just variable substitution in the docs, but in code that first has the substitutions, and is then built, compiled, tested, and then is just a regular snippet include for the docs. Having these examples tested is much easier for maintaining the docs.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/cloudstateio/cloudstate/issues/306#issuecomment-638478174, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFOUG64D3XDQGROUWWNBSZTRU276RANCNFSM4M26FA5A .

-- Ruth Stento User Experience Lead Lightbend

512-696-1448 http://lightbend.com