Include Java example code excerpts

[zeitlinger]

No description provided.

[zeitlinger]

@svrnm can you help with the build error?

[svrnm]

@svrnm can you help with the build error?

@chalin knows best how the code excerpts work, let's wait for him to be back and take a look!

[svrnm]

@chalin can you take a look? Or should we currently not introduce more pages that use the code excerpt?

[chalin]

Thanks for the ping and your patience. Great work here @zeitlinger!

Could you rebase and resolve the conflicts and I'll take a look. I'm OOO next week, but try to work on this PR tomorrow if you can get the conflicts resolved by then.

@chalin can you take a look? Or should we currently not introduce more pages that use the code excerpt?

I think that it is worth bring in this PR.

Oh that build error was tricky to resolve. I can't recall how I worked through it the last time, but I'll find out when I next work on this PR.

[zeitlinger]

@chalin merge conflict resolved

[chalin]

Great work here @zeitlinger!

I've fixed the build issue:

And I tweaked the position of directives so that they don't appear in auto-generated page description metadata.

Note that I haven't reviewed the content of this PR carefully. My main focus in this review was from a tooling/page generation perspective. But from that perspective, this PR LGTM ✨

[chalin]

@open-telemetry/java-approvers @open-telemetry/java-instrumentation-approvers PTAL

[chalin]

Btw, @zeitlinger - the script supports many options that allow you to adjust the code excerpts that are pulled in, including the use of from and to regexs. You can also named regions in the code and pull in named regions only. The nice thing about named regions is that they don't even need to be contiguous: e.g., you can excerpt part of one function here, and another function there. But what you have here seems quite fine for now, I just wanted to mention some of the direction's options in case you didn't know about them.

[zeitlinger]

@chalin can you check?

[chalin]

@chalin can you check?

@zeitlinger - do you mean check if named regions would be a useful feature to apply in this PR? I won't have the time to do that. I suggest that we get this merged first.

We're still waiting for the following approvals from Java SIG approvers:

• @open-telemetry/java-approvers
• @open-telemetry/java-instrumentation-approvers

[zeitlinger]

@zeitlinger - do you mean check if named regions would be a useful feature to apply in this PR? I won't have the time to do that. I suggest that we get this merged first.

I actually like the fact that all files are complete and can be copied as is

[svrnm]

@zeitlinger can you check with Java SIG to have someone review and approve, then happy to merge this:-)

[jack-berg]

This is cool! I'm not familiar with all of the mechanics of how code snippets are referenced / injected, but the code in the java snippets looks good to me.

[svrnm]

This is cool! I'm not familiar with all of the mechanics of how code snippets are referenced / injected, but the code in the java snippets looks good to me.

@chalin added some tooling for that from the dart project. We are still in a "public beta" phase of that tooling, but it looks promising, but it's also still a manual process to get things updated, etc.

Thanks for the review!

[chalin]

Thank you @zeitlinger, @svrnm, et al. I'm glad that this got merged!
My plan, in the next couple of months I'll work on simplifying the tool chain (FYI)