Add tooling in support of auto-update of code excerpts in docs

[chalin]

@svrnm - I remember you mentioning this somewhere, but I can't find the reference. Anyhow, I'm creating this issue to track progress on this work. /cc @cartermp

At the start of the year I introduced a simple verbatim code-copy shortcode, but what I have in mind would be more flexible.

• [CI] Support code-snippet extraction and docs-updating #3948
• Replace Dart-based tooling with JS/Node-based versions
  • Investigate JS-based tooling feature set. Might it be a drop-in replacement? [Add a reference here to the JS-based tooling.]

Tooling use:

• Include Java example code excerpts #4642

[svrnm]

we discussed that on slack and/or the comms call a few months back, but I can't find it either.

Curious to see & discuss what you have in mind

[ekquasar]

There's the issue of keeping the code snippets in the docs updated to reflect working example code - and that is the topic of this issue, iiuc? But then there's the issue of keeping the example code tested. Is that also the subject of this issue?

[svrnm]

We discussed this during yesterday's SIG meeting. @chalin will provide a proposal following some best practices other projects have implemented today already. For testing the go/example/dice and the go getting started will be used (cc @pellared, who has contributed both)

@ekquasar the PR may or may not answer your question around keeping things in sync, so let's wait for what @chalin's prototype will look like, early next year.

[zeitlinger]

I'm in the process of adding more snippets, so this feature would be great.

See #4642

[svrnm]

@zeitlinger we have tooling place, see #3948 and some of the Go Docs related to that, it's still under observation, but you can take a look and see if you can make use of it for java as well

[zeitlinger]

why are the go samples not up-to-date then?

[svrnm]

why are the go samples not up-to-date then?

they aren't? I guess because it is still a manual process to update them (cc @chalin)

[chalin]

Yes, given that this is still in development (and I'm hoping to bring in simpler tooling as soon as I have time to devote to this), the process is still manual.

[chalin]

Let me refresh those code excerpts now.

[svrnm]

Let me refresh those code excerpts now.

#4678 I gave it a try 🙈 , since some of the code has been put into a separate file this is not only an update but also needs some textual changes

[chalin]

Thanks @svrnm. I'll let you handle it from here.