[ON week] Add language client examples to get-started/index-basics.md

[leemthompo]

Uses https://github.com/elastic/request-converter

An ON Week Python script automates adding multi-language code examples to docs pages.

• Finds console code blocks in markdown files
• Converts them to multiple languages (Python, JS, PHP, Ruby, curl) using es-request-converter CLI
• Pulls everything into snippets files
• Wraps results in tab-sets (handles incrementing outermost colons in directives to work with steppers etc.)
• Handles annotations, localhost replacement, and formatting quirks
• Works around two bugs found in the converter itself (fixed in meantime!)

I'll share and "document" the script itself as part of ON week summary.

[github-actions]

🔍 Preview links for changed docs

• solutions/search/get-started/index-basics.md

[leemthompo]

It's necessary to pull all the examples into separate snippets and include them, otherwise it balloons the source page enormously. However, I'm on the fence about whether the console blocks should also be snippetized.
I think the authoring experience becomes more opaque when those console blocks aren't on the page itself, and it makes it even harder for infrequent contributors to make even trivial typo fixes in code blocks. Food for thought.

The latest iteration of my script has a -- regenerate option which wipes all the language examples and reconverts remaining console blocks.

[leemthompo]

Putting this up for review for anybody interested in the approach, all feedback is welcome :)

[lcawl]

... However, I'm on the fence about whether the console blocks should also be snippetized...

Would keeping the console example in a snippet make it easier to automatically re-generate the language client examples whenever the console example changes? If so, that might be a compelling reason to keep it "snippetized".

BTW IMO it would be useful to have a comment at the top of the languages client snippets saying (1) they're generated, so don't edit them directly, and (2) a readme for how to re-generate them, which it sounds like you're already planning.

[leemthompo]

Would keeping the console example in a snippet make it easier to automatically re-generate the language client examples whenever the console example changes? If so, that might be a compelling reason to keep it "snippetized".

It would definitely simplify the mental model of how regeneration works, but I'm also trying to imagine the authoring experience if you want to remove or add code blocks, which might get a bit involved. My initial concern would be that we increase the difficulty of contribution by hiding the console stuff away from the page it's rendered on, 🤷.

Although if it was clearly documented that you just need to work within the snippets directory and then regenerate then that should be fine I guess. It will definitely block simple fixes on the web but there has to be a tradeoff somewhere.

As mentioned in my ON week recap too, would need to make sure this is all compatible with George and Istvan's testing framework if we decide to implement either.

BTW IMO it would be useful to have a comment at the top of the languages client snippets saying (1) they're generated, so don't edit them directly, and (2) a readme for how to re-generate them, which it sounds like you're already planning.

💯