Automatically generate examples documentation (#19294)

[cj-zhukov]

Which issue does this PR close?

• part of #Automatically generate examples documentation and add CI sync check #19294.

Rationale for this change

What changes are included in this PR?

Are these changes tested?

Are there any user-facing changes?

[cj-zhukov]

High-Level Overview

This PR introduces a helper script generate_examples_docs.sh for generating examples documentation in a consistent format. The script discovers example groups and subcommands and emits a Markdown table skeleton that matches the structure enforced by the CI documentation check.
It can be used to generate documentation for all example groups:

 ./ci/scripts/generate_examples_docs.sh

or for a specific group:

 ./ci/scripts/generate_examples_docs.sh --group builtin_functions

[cj-zhukov]

@Jefffrey since you helped review and discuss the earlier examples documentation PR, you might be interested in this follow-up as well. This one adds a small helper script to generate example documentation in the format enforced by the CI check. Feedback is very welcome.

[Jefffrey]

Is the intention to eventually have two scripts, one to check and one to generate? They seem quite similar, and I think a common pattern we have is to only have the generate script, then in CI we rerun the generate script and do a git diff to ensure they are matching.

[cj-zhukov]

Is the intention to eventually have two scripts, one to check and one to generate? They seem quite similar, and I think a common pattern we have is to only have the generate script, then in CI we rerun the generate script and do a git diff to ensure they are matching.

Good point, thanks for calling this out.

It makes sense to rely on a single generate script and have CI re-run it and check for diffs, rather than maintaining separate generate and check logic.

I can update this PR to drop the standalone check script and wire CI to run generate_examples_docs.sh and fail on git diff instead.

[Jefffrey]

Is the intention to eventually have two scripts, one to check and one to generate? They seem quite similar, and I think a common pattern we have is to only have the generate script, then in CI we rerun the generate script and do a git diff to ensure they are matching.

Good point, thanks for calling this out.

It makes sense to rely on a single generate script and have CI re-run it and check for diffs, rather than maintaining separate generate and check logic.

I can update this PR to drop the standalone check script and wire CI to run generate_examples_docs.sh and fail on git diff instead.

That sounds good

[cj-zhukov]

The work described in this draft PR was completed in #19750, which has now been merged.
Therefore this draft is no longer needed and can be closed.