DOC-5517 TCE local_examples subfolders and named params for clients-examples

[andy-stark-redis]

DOC-5517

Does exactly what it says on the tin :-) There's a test file at the top of the Develop section to demonstrate the shortcode changes; I'll remove it before merging.

Some things to consider:

• We can have any subfolder names we like in local_examples. Just floating a proposal that we have a temp folder for stuff that should eventually get merged into the release branch of a client repo (so we can periodically check for redundant files here). Any other stuff should be permanently local, so we can use whatever structuring is appropriate in each case.
• The parameter names for the shortcodes are just suggestions. If you think of more helpful names then I'm happy to change them.
• The shortcode can actually support positional parameters (in the existing order) or named parameters equally well, as long as you don't mix the two in any instance of the shortcode. I'm thinking maybe we could stick with the positional params for most of the current examples that only use the set and step names? Anyway, there's no urgent need to update the existing examples, but we can do that in the future if we decide it's better.

[github-actions]

Staging links:
https://redis.io/docs/staging/DOC-5517-more-tce-stuff/develop/clients-example-test

[dwdougherty]

This looks great, @andy-stark-redis! Just curious: what happens when the same code example is found in both a client repo and the local_examples folder? This should probably be tested, as it's inevitable that one of us (prolly me) will forget to remove an example from local after an example is merged in a client repo.

Also, I agree about the use of a "temp" directory, although this old Unix dog bristles at temp vs tmp. :) Additionally, I think it's okay to leave the existing examples as is, but use the named parameters going forward.

[andy-stark-redis]

@dwdougherty Yeah, I did test that situation - the local example gets priority. One the one hand, this means we can make temporary fixes to dodgy examples quickly instead of waiting for them to be approved on client repo. On the other hand, we have to delete the local file to get what's merged to the client repo. I slightly prefer giving priority to the local examples, but we could change this if it turns out to be a problem.

We can use tmp if you like :-) As you say, no hurry with updating the examples, but named params are more self-explanatory (and maybe better for AI to parse?)

[dwdougherty]

Awesome. Thank you for testing that, and I agree that it's probably better for the local examples to override client examples.