Support selecting programming language in code snippets

[szabosteve]

Is this feature required for your content to migrate?
It is not required for migration.

Describe the solution you need
The documentation often contains code snippets as examples of an operation. The code snippets are "Console" commands by default but it would be great to have the option to select another language and see the example in that language.

Impact
With this feature, repeating the same commands in various languages on the same page is unnecessary. One snippet could contain and display the commands for all the available languages.

Additional context

[scottybollinger]

@szabosteve do you have an example of this in the legacy (current) docs that I can use for reference? Thanks!

[szabosteve]

@scottybollinger Well, this was the page where I took the screenshot above: https://www.elastic.co/guide/en/cloud/current/ec-working-with-elasticsearch-clients.html#ec_connect_a_client
It has been deleted since then and – according to the conf.yml in elastic/docs – all the previous branches have been mapped to Clients: https://github.com/elastic/docs/blob/master/conf.yaml#L85. So I cannot link to a previous version of that page either. The asciidoc file is still available in a previous branch of the repo though: https://github.com/elastic/cloud/blob/ms-80/docs/shared/ec-ce-working-with-elasticsearch.asciidoc. I hope it helps a bit.

We do have other examples in the current docs, however, for example on the create index API page. Sadly, the function does not work here since the project was stopped.

I don't know if these are helpful to any degree. Please let me know if I can help anyhow.

[scottybollinger]

@colleenmcginnis, do you happen to know of an example of legacy docs that have a language-switching component with multiple languages actually used? The example above only has one language for each example and I'd like to see how one with multiple languages works. Thanks!

[colleenmcginnis]

I can't find any with language switching that actually works. I brought this to #docs in Slack to see if this is expected to work anywhere. I'll post back when I get a response.

In the meantime, I don't think switching languages is a high priority for docsmobile. We haven't, however, had a discussion about the other functionality available in the console_widget. The user can click the gear icon to specify a few settings, save them, and then close out of the modal and click the View in Console button to open Kibana's console with the snippet pre-populated and ready to run.

This functionality is available in the example @szabosteve linked to in his last comment: Create index API.

However, I don't think we have any data on how many users take advantage of this feature (I think I may have asked @KOTungseth in passing at some point) so I'm not sure if it's worth investing the time in building out this feature right now. To get a clearer picture of the need, I could open up a writer discussion and open a fresh issue here if there's engineering work to do.

[scottybollinger]

The user can click the gear icon to specify a few settings, save them, and then close out of the modal and click the View in Console button to open Kibana's console with the snippet pre-populated and ready to run.

Thanks! I saw this as well and think it should be fairly simple to implement.

[colleenmcginnis]

It looks like there are a few examples of these drop downs working (see Slack thread), but that the functionality has probably been largely broken for quite a while (maybe even since 2020). My guess (without knowing exactly how it works) is that it stopped working at some point (2020-ish), but snippets that use language drop downs that haven't been added/edited since it broke might still work because the alternative language snippets were already generated.

In my opinion, we should have a discussion about this functionality before committing dev resources to building it into docsmobile. The discussion could include:

• Should we attempt to fix this functionality in the current AsciiDoc system? If so, who will fix it? If not, can we remove the broken drop downs that are currently on the live docs site?
• Should we prioritize adding this feature to docsmobile ahead of migration since it doesn't currently work in AsciiDoc? Could we delay development and go back to it as a new feature rather than part of reaching feature parity with AsciiDoc?
• Since no one (that I've heard from) knows how we autogenerate snippets in alternative languages and how they are pulled into the docs, should we do some discovery around what we want out of a feature like this and start from scratch in docsmobile rather than trying to understand how it works in the current AsciiDoc system?

What do you think about this approach @scottybollinger @szabosteve @KOTungseth?

[scottybollinger]

It looks like there are a few examples of these drop downs working (see Slack thread), but that the functionality has probably been largely broken for quite a while (maybe even since 2020). My guess (without knowing exactly how it works) is that it stopped working at some point (2020-ish), but snippets that use language drop downs that haven't been added/edited since it broke might still work because the alternative language snippets were already generated.

In my opinion, we should have a discussion about this functionality before committing dev resources to building it into docsmobile. The discussion could include:

• Should we attempt to fix this functionality in the current AsciiDoc system? If so, who will fix it? If not, can we remove the broken drop downs that are currently on the live docs site?
• Should we prioritize adding this feature to docsmobile ahead of migration since it doesn't currently work in AsciiDoc? Could we delay development and go back to it as a new feature rather than part of reaching feature parity with AsciiDoc?
• Since no one (that I've heard from) knows how we autogenerate snippets in alternative languages and how they are pulled into the docs, should we do some discovery around what we want out of a feature like this and start from scratch in docsmobile rather than trying to understand how it works in the current AsciiDoc system?

What do you think about this approach @scottybollinger @szabosteve @KOTungseth?

Thanks, Colleen! I agree 100% with this proposal. I am going to unassign, remove this from in progress, and place in the backlog. We can revisit once a decision has been made.

If we decide to deprioritize this completely for the migration, I can remove it from the Current Work project.

[KOTungseth]

We have a few issues in the Kibana repo for the broken API docs functionality. A few people have worked on them over the years, but nothing has been resolved. Since we don't collect metrics on these components in the docs, I'm not sure how often they are used.

For the Serverless API docs functionality, I think we need input from a technical perspective and a design perspective on whether or not we need this functionality to GA.

[sethmlarson]

Hello! 👋 I'm from the clients team, we've been getting many requests for more extensive examples for language clients and we see these auto-generated API request examples as a great way to fulfill this customer request. @picandocodigo did some digging into the current state of the end-to-end pipeline for these examples and we found that everything is still operational from our POV, we've been able to update generated examples and have those changes appear on elastic.co. Full investigation here: https://github.com/elastic/clients-team/issues/577

We'd like to get more examples generated (previously we had an per-page incremental rollout for our examples, but there's no foundational reason we couldn't just "generate everything" beyond ensuring that the examples are valid). We'd also like to add examples for more languages, currently per this report we only have some examples for PHP, Python, Ruby, Go, and JS:

{
  "console": {
    "total": 3711,
    "alternatives": {
      "php": {
        "found": 75
      },
      "python": {
        "found": 74
      },
      "ruby": {
        "found": 289
      },
      "go": {
        "found": 200
      },
      "js": {
        "found": 74
      }
    }
  }
}

Hopefully we can also have this support in the next docs system as well?

[lcawl]

This is a total fly-by comment, but does the tabs functionality in docsmobile help address this request?