Embed source code snippets from example repos

[zeitlinger]

I'd like to embed code snippets on the website

• using https://github.com/grafana/embedmd (or something similar)
• from https://github.com/open-telemetry/opentelemetry-java-examples
• to https://opentelemetry.io/docs/languages/java/

[svrnm]

Thanks @zeitlinger, just adding some of our slack conversation for context:

• We already support embedding code (and keeping it in sync) via code_excerpter, as implemented in this PR for go getting started: [CI] Support code-snippet extraction and docs-updating #3948
• This implementation is still under test, so we try to not open the flood gates yet. I would be open to add this as yet another example, but I would like to get other maintainers (and especially @chalin) to express their opinion.

[zeitlinger]

Great - I'll just wait for more feedback on this issue 😄

[theletterf]

I suggest moving this to Discussion.

[chalin]

As Severin pointed out in Slack, we have some tooling setup for code snippet refresh already, and it's tooling that has been used (for almost 9 years) and continues to be in use at Google, so it is well vetted; and the tools continue to be updated -- for the (current) canonical home of the tools, see https://github.com/dart-lang/site-shared/tree/main/packages. (Insider note that a JS rewrite of the tooling is in the works.)

I took a quick look at embedmd and I get the impression that it figures out which lines of code to bring in based on regexes. This is only one of the snippet extraction modes supported by the current tools, and generally not the preferred one given that it can be brittle. In the experiences I've had at Google maintaining websites with lots of code snippets, generally the best option (least brittle) is to add annotations to the source files for the purpose of delimiting code snippets. This makes it more obvious to developers when they update the code as to whether their changes might impact (and possibly break) code snippet extraction.

That being said, if you want to only use regexes with the current tooling you can.

I hope this helps.

FYI, I'm at half time this month and OOO all of next week. I'd be glad to work through a more complete example of the use of the current tooling, but it probably won't be until the end of the month. I'll do my best to answer any questions you might have as soon as I'm available.

[svrnm]

I suggest moving this to Discussion.

I think this is a very concrete ask (add code sync for java) with a binary answer (yes we do this, here is a PR, no we don't do this, close this issue), so a discussion might not be necessary.

on topic @chalin: would you be fine with @zeitlinger creating a PR for what he wants to accomplish using the current tooling (code_excerpter)?

[chalin]

@chalin: would you be fine with @zeitlinger creating a PR for what he wants to accomplish using the current tooling (code_excerpter)?

Yes, of course! 🙌🏻

There is one tweak that I want to make to the tooling so that it plays more nicely with Prettier, but the tools are usable as is.