feat(clients): more manual snippets for doc (#4452)

Co-authored-by: shortcuts <[email protected]>

Author: Fluf22

config/generation.config.mjs

@@ -24,8 +24,6 @@ export const patterns = [
   '!clients/algoliasearch-client-csharp/algoliasearch/Transport/**',
   '!clients/algoliasearch-client-csharp/algoliasearch/Models/Common/**',
 
-  '!docs/guides/csharp/src/program.cs',
-
   'tests/output/csharp/global.json',
 
   // Dart
@@ -52,8 +50,6 @@ export const patterns = [
   '!clients/algoliasearch-client-go/algolia/debug/*',
   '!clients/algoliasearch-client-go/algolia/utils/*',
 
-  '!docs/guides/go/src/main.go',
-
   '!tests/output/go/go.*',
 
   // Java
@@ -104,14 +100,6 @@ export const patterns = [
   '!clients/algoliasearch-client-php/lib/Configuration/ConfigWithRegion.php',
   'clients/algoliasearch-client-php/composer.json',
 
-  'docs/guides/php/**',
-  '!docs/guides/php/.gitignore',
-  '!docs/guides/php/composer.json',
-  '!docs/guides/php/phpstan.neon',
-  'docs/guides/php/composer.phar',
-  'docs/guides/php/composer.lock',
-  'docs/guides/php/vendor/**',
-
   // Python
   'clients/algoliasearch-client-python/**',
   '!clients/algoliasearch-client-python/algoliasearch/http/**',
@@ -127,8 +115,6 @@ export const patterns = [
   '!tests/output/python/**/__init__.py',
   'tests/output/python/requirements.txt',
 
-  'docs/guides/python/**',
-  '!docs/guides/python/pyproject.toml',
 
   // Ruby
   '!clients/algoliasearch-client-ruby/**',

docs/guides/php/composer.json

@@ -1,4 +1,10 @@
 {
+  "repositories": [
+    {
+      "type": "path",
+      "url": "../../../clients/algoliasearch-client-php"
+    }
+  ],
   "require": {
     "algolia/algoliasearch-client-php": "*",
     "ext-json": "*"

generators/src/main/java/com/algolia/codegen/cts/guides/GuidesGenerator.java

@@ -46,6 +46,24 @@ public void addSupportingFiles(List<SupportingFile> supportingFiles, String outp
         )
       );
     }
+
+    switch (language) {
+      case "csharp":
+        supportingFiles.add(
+          new SupportingFile("guides/program.mustache", "docs/guides/" + language + outputFolder + "program" + extension)
+        );
+        break;
+      case "go":
+        supportingFiles.add(new SupportingFile("guides/main.mustache", "docs/guides/" + language + outputFolder + "main" + extension));
+        break;
+      case "php":
+        supportingFiles.add(new SupportingFile("guides/.gitignore", "docs/guides/" + language + outputFolder + ".gitignore"));
+        supportingFiles.add(new SupportingFile("guides/composer.json", "docs/guides/" + language + outputFolder + "composer.json"));
+        supportingFiles.add(new SupportingFile("guides/phpstan.neon", "docs/guides/" + language + outputFolder + "phpstan.neon"));
+        break;
+      default:
+        break;
+    }
   }
 
   @Override

generators/src/main/java/com/algolia/codegen/cts/tests/ParametersWithDataType.java

@@ -181,7 +181,12 @@ private Map<String, Object> traverseParams(
     }
 
     // for snippets, we want pretty index names, unless they are already pretty
-    if (prettyIndexName && paramName.equals("indexName") && !((String) testOutput.get("value")).startsWith("<")) {
+    if (
+      prettyIndexName &&
+      paramName.equals("indexName") &&
+      !((String) testOutput.get("value")).startsWith("<") &&
+      !((Boolean) testOutput.getOrDefault("isVerbatim", false))
+    ) {
       testOutput.put("value", "<YOUR_INDEX_NAME>");
     }
 

scripts/ci/codegen/pushToRepository.ts

@@ -158,6 +158,8 @@ async function pushToRepository(repository: string, config: RepositoryConfigurat
       head: task.prBranch,
     });
 
+    await run(`gh pr merge ${data.number} --auto`);
+
     console.log(`Pull request created on ${OWNER}/${repository}`);
     console.log(`  > ${data.url}`);
   }

scripts/common.ts

@@ -10,7 +10,7 @@ import clientsConfig from '../config/clients.config.json' with { type: 'json' };
 import releaseConfig from '../config/release.config.json' with { type: 'json' };
 
 import { Cache } from './cache.ts';
-import { getDockerImage, getTestOutputFolder } from './config.ts';
+import { getClientsConfigField, getDockerImage } from './config.ts';
 import { generateOpenapitools } from './pre-gen/index.ts';
 import { getGitAuthor } from './release/common.ts';
 import { buildSpecs } from './specs/index.ts';
@@ -294,9 +294,12 @@ export async function setupAndGen(
 
   for (const gen of generators) {
     if (mode === 'guides') {
-      await run(`rm -rf ${path.join('docs', mode, gen.language, getTestOutputFolder(gen.language))}`, {
-        language: gen.language,
-      });
+      await run(
+        `rm -rf ${path.join('docs', mode, gen.language, getClientsConfigField(gen.language, ['snippets', 'outputFolder']))}`,
+        {
+          language: gen.language,
+        },
+      );
     }
 
     const spinner = createSpinner(`generating ${mode} for ${gen.key}`);

templates/csharp/guides/program.mustache

@@ -0,0 +1,6 @@
+namespace Algolia;
+
+public static class Program
+{
+  public static void Main() { }
+}

templates/csharp/guides/search/enableFilterPromote.mustache

@@ -0,0 +1,32 @@
+namespace Algolia;
+
+using System;
+using System.Text.Json;
+using System.Net.Http;
+using System.Collections.Generic;
+
+{{> snippets/import}}
+
+class EnableFilterPromote {
+
+  async Task Main(string[] args)
+  {
+    var condition = new Condition
+    {
+      Anchoring = Anchoring.Is,
+      Pattern = "{facet:brand}"
+    };
+
+    var consequence = new Consequence
+    {
+      FilterPromotes = true
+    };
+
+    var rule = new Rule
+    {
+      ObjectID = "rule_with_filterPromotes",
+      Conditions = [condition],
+      Consequence = consequence
+    };
+  }
+}

templates/csharp/guides/search/searchInReplicaIndex.mustache

@@ -0,0 +1,33 @@
+namespace Algolia;
+
+using System;
+using System.Text.Json;
+using System.Net.Http;
+using System.Collections.Generic;
+
+{{> snippets/import}}
+
+class SearchInReplicaIndex {
+
+  async Task Main(string[] args)
+  {
+
+    try {
+      {{> snippets/init}}
+
+      var query = "query";
+
+      // 1. Change the sort dynamically based on the UI events
+      var sortByPrice = false;
+
+      // 2. Get the index name based on sortByPrice
+      var indexName = sortByPrice ? "products_price_desc" : "products";
+
+      // 3. Search on dynamic index name (primary or replica)
+      {{#dynamicSnippet}}searchWithIndexNameVar{{/dynamicSnippet}};
+    } catch (Exception e) {
+      Console.WriteLine(e.Message);
+    }
+  }
+}
+

templates/csharp/guides/search/searchWithAnalyticsAndHeader.mustache

@@ -0,0 +1,33 @@
+namespace Algolia;
+
+using System;
+using System.Text.Json;
+using System.Net.Http;
+using System.Collections.Generic;
+
+{{> snippets/import}}
+
+class SearchWithAnalyticsAndHeader {
+
+  async Task Main(string[] args)
+  {
+
+    try {
+      {{> snippets/init}}
+
+      /*
+      '94.228.178.246' should be replaced with your user's IP address.
+      Depending on your stack there are multiple ways to get this information.
+      */
+      var ip = "94.228.178.246";
+      var query = "query";
+
+      var searchParams = new SearchParams(new SearchParamsObject { Query = query, Analytics = true });
+
+      {{#dynamicSnippet}}searchWithSearchParamsAndForwardedHeader{{/dynamicSnippet}};
+    } catch (Exception e) {
+      Console.WriteLine(e.Message);
+    }
+  }
+}
+

templates/csharp/guides/search/searchWithLogicalOr.mustache

@@ -0,0 +1,34 @@
+namespace Algolia;
+
+using System;
+using System.Text.Json;
+using System.Net.Http;
+using System.Collections.Generic;
+
+{{> snippets/import}}
+
+class SearchWithLogicalOr {
+
+  async Task Main(string[] args)
+  {
+
+    try {
+      {{> snippets/init}}
+
+      var query = "the query";
+
+      var optionalWords = new OptionalWords(["the", "query"]);
+
+      var searchParams = new SearchParams(new SearchParamsObject
+      {
+        Query = query,
+        OptionalWords = optionalWords
+      });
+
+      {{#dynamicSnippet}}searchWithSearchParams{{/dynamicSnippet}};
+    } catch (Exception e) {
+      Console.WriteLine(e.Message);
+    }
+  }
+}
+

templates/csharp/guides/search/useConditionlessRule.mustache

@@ -0,0 +1,33 @@
+namespace Algolia;
+
+using System;
+using System.Text.Json;
+using System.Net.Http;
+using System.Collections.Generic;
+
+{{> snippets/import}}
+
+class UseConditionlessRule {
+
+  async Task Main(string[] args)
+  {
+
+    try {
+      {{> snippets/init}}
+
+      var objectID = "a-rule-id";
+
+      var rule = new Rule
+      {
+        ObjectID = objectID,
+        Consequence = new Consequence(/* Set relevant consequence */),
+        // Set validity (optional)
+        Validity = [new TimeRange { From = 1688774400L, Until = 1738972800L }]
+      };
+
+      {{#dynamicSnippet}}saveRule{{/dynamicSnippet}};
+    } catch (Exception e) {
+      Console.WriteLine(e.Message);
+    }
+  }
+}

templates/dart/guides/search/enableFilterPromote.mustache

@@ -0,0 +1,19 @@
+{{> snippets/import}}
+
+void enableFilterPromote() async {
+  final condition = Condition(
+    pattern: "{facet:brand}",
+    anchoring: Anchoring.is_,
+  );
+
+  final consequence = Consequence(
+    filterPromotes: true
+  );
+
+  // ignore: unused_local_variable
+  final rule = Rule(
+    objectID: "rule_with_filterPromotes",
+    conditions: [condition],
+    consequence: consequence
+  );
+}

templates/dart/guides/search/savePopularRecords.mustache

@@ -12,9 +12,10 @@ void savePopularRecords() async {
         indexName: "indexName", browseParams: browseParams
     );
     for (final hit in browseResponse.hits) {
-      final isPopular = hit['nbFollowers'] > 1000;
+      final props = hit.toJson();
+      final isPopular = props['nbFollowers'] > 1000;
       final updatedProduct = {
-        ...hit,
+        ...props,
         'isPopular': isPopular,
       };
       records.add(updatedProduct);

templates/dart/guides/search/searchInReplicaIndex.mustache

@@ -0,0 +1,15 @@
+{{> snippets/import}}
+
+void searchInReplicaIndex() async {
+  {{> snippets/init}}
+
+  // 1. Change the sort dynamically based on the UI events
+  final sortByPrice = false;
+
+  // 2. Get the index name based on sortByPrice
+  // ignore: dead_code
+  final indexName = sortByPrice ? "products_price_desc" : "products";
+
+  // 3. Search on dynamic index name (primary or replica)
+  await {{#dynamicSnippet}}searchWithIndexNameVar{{/dynamicSnippet}};
+}

templates/dart/guides/search/saveRecentlyPublishedBooks.mustache renamed to templates/dart/guides/search/searchRecentlyPublishedBooks.mustache

@@ -0,0 +1,20 @@
+{{> snippets/import}}
+
+void searchWithAnalyticsAndHeader() async {
+  {{> snippets/init}}
+
+  /*
+  '94.228.178.246' should be replaced with your user's IP address.
+  Depending on your stack there are multiple ways to get this information.
+  */
+  final ip = "94.228.178.246";
+  final query = "query";
+
+  final searchParams = SearchParamsObject(
+      query: query,
+      analytics: true
+  );
+
+  await {{#dynamicSnippet}}searchWithSearchParamsAndForwardedHeader{{/dynamicSnippet}};
+}
+

templates/dart/guides/search/searchWithAnalyticsAndHeader.mustache

@@ -0,0 +1,12 @@
+{{> snippets/import}}
+
+void searchWithLogicalOr() async {
+    {{> snippets/init}}
+    final query = "the query";
+    final optionalWords = ["the", "query"];
+    final searchParams = SearchParamsObject(
+        query: query,
+        optionalWords: optionalWords,
+    );
+    await {{#dynamicSnippet}}searchWithSearchParams{{/dynamicSnippet}};
+}