guides: add new generator

[millotp]

🧭 What and Why

🎟 JIRA Ticket: https://algolia.atlassian.net/browse/DI-2974 https://algolia.atlassian.net/browse/DI-2975 https://algolia.atlassian.net/browse/DI-2976

Changes included:

supersede #3836

this PR adds a new generator in order to be able to generate guides.

Context

The onboarding team creates guides using the API client plus some other external libraries (e.g. fetch) in order to showcase how to push data to Algolia.

Today they only provide snippets for JavaScript, and it requires us manual intervention, manual testing, linting etc.

They'd like to be able to keep their guides up to dates with our API clients, and at some point, provide guides for more languages than just JavaScript.

In their initial RFC, they were proposing to create a CI that does exactly what we do, so in order to platformize a bit more our repository, @shortcuts suggested to leverage our tooling to generate their guides

How does it work

This PR is not complete, we are missing a few things that will be tackled in https://algolia.atlassian.net/browse/DI-2984 and https://algolia.atlassian.net/browse/DI-2985 but the goal is simple

From a mustache file (located in templates/${language}/guides/${api}), and a guide definition (located in tests/CTS/guides/${api}), generate a fully working guide, self contained file, for every available clients.

Example

I create my templates/go/guides/search/saveObjectsWithSofa.mustache file:

{{> snippets/import}}

{{> snippets/init}}

// do boilerplate stuff with sofa
return {{#dynamicSnippet}}saveObjectsWithSofa{{/dynamicSnippet}}

The dynamic snippet template will read the tests/CTS/guides/search/snippets.json:

{
  "saveObjectsWithSofa": {
    "method": "saveObjects",
    "parameters": {
      "indexName": "sofaaa",
      "objects": [
        {
          "$var": "objects"
        }
      ]
    }
  }
}

The key that has been passed to the dynamic template (saveObjectsWithSofa) is there and contains the method to find in the spec, and the parameters to feed it. The parametersWithDataType logic is the same as for the tests and snippets generator, as well as for the mustaches file.

You can now write for example templates/php/guides/search/saveObjectsWithSofa.mustache, the process will be the same.

Other changes

We don't need to have the snippets folder/files anymore, just the JSON file output for the documentation. So we removed it from the repo, and ignored it, it now only lives on the CI

[algolia-bot]

✔️ Code generated!

Name	Link
🪓 Triggered by	d1a7b547f0e4b90316534ceb461edaea657dbb88
🍃 Generated commit	5cab092ff18bbe36ba091384a400775b5e285e7b
🌲 Generated branch	generated/feat/guides-gen

📊 Benchmark results

Benchmarks performed on the method using a mock server, the results might not reflect the real-world performance.

Language	Req/s
javascript	1663
go	1591
php	1460
csharp	1349
java	1129
python	1029
ruby	888
swift	755

[shortcuts]

yes

[shortcuts]

i've rarely seen a pr this perfect

[github-actions]

🚀 Deployed on https://66fd6d5993a391284ca2c41b--api-clients-automation.netlify.app

[shortcuts]

of course it's perfect

[shortcuts]

This is wonderful