Merge branch 'main' into fix/release-PR-and-process

README.md

@@ -14,13 +14,13 @@ nvm use && yarn
 yarn docker:setup
 ```
 
-[Read more on our documentation](https://api-clients-automation.netlify.app/docs/automation/setup-repository)
+[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/setup-repository)
 
 ## Contributing
 
 You can make changes locally and run commands through the docker container.
 
-[Specs CLI commands](https://api-clients-automation.netlify.app/docs/automation/CLI/specs-commands) • [Clients CLI commands](https://api-clients-automation.netlify.app/docs/automation/CLI/clients-commands) • [CTS CLI commands](https://api-clients-automation.netlify.app/docs/automation/CLI/cts-commands)
+[Specs CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/specs-commands) • [Clients CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/clients-commands) • [CTS CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/cts-commands)
 
 ### Build and validate specs
 
@@ -30,7 +30,7 @@ You can make changes locally and run commands through the docker container.
 yarn docker build specs <client | all>
 ```
 
-[Read more on our documentation](https://api-clients-automation.netlify.app/docs/automation/add-new-api-client)
+[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/add-new-api-client)
 
 ### Generate clients based on the [`specs`](./specs/)
 
@@ -40,11 +40,11 @@ yarn docker build specs <client | all>
 yarn docker generate <language | all> <client | all>
 ```
 
-[Read more on our documentation](https://api-clients-automation.netlify.app/docs/automation/add-new-language)
+[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/add-new-language)
 
 ## Testing clients
 
 You can test our generated clients by running:
 
-- The playground [`playground`](./playground) ([Playground](https://api-clients-automation.netlify.app/docs/automation/testing/playground.md))
-- Tests with our [`Common Test Suite`](./tests/) ([Common Test Suite](https://api-clients-automation.netlify.app/docs/automation/testing/common-test-suite.md)).
+- The playground [`playground`](./playground) ([Playground](https://api-clients-automation.netlify.app/docs/contributing/testing/playground.md))
+- Tests with our [`Common Test Suite`](./tests/) ([Common Test Suite](https://api-clients-automation.netlify.app/docs/contributing/testing/common-test-suite.md)).

website/docs/api-clients/guides/send-data-to-algolia.mdx → website/docs/clients/guides/send-data-to-algolia.mdx

@@ -15,7 +15,7 @@ To push data to Algolia, you need an Application ID and a valid API key with the
 
 ## Setting up the API client
 
-> [Make sure to also read the Installation page](/docs/api-clients/installation).
+> [Make sure to also read the Installation page](/docs/clients/installation).
 
 <Tabs
   groupId="language"
@@ -40,13 +40,14 @@ const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
 </TabItem>
 <TabItem value="php">
 
-  ```php
-  <?php
-  $client = Algolia\AlgoliaSearch\Api\SearchClient::create(
-    '<YOUR_APP_ID>',
-    '<YOUR_API_KEY>'
-  );
-  ```
+```php
+<?php
+$client = Algolia\AlgoliaSearch\Api\SearchClient::create(
+  '<YOUR_APP_ID>',
+  '<YOUR_API_KEY>'
+);
+```
+
 </TabItem>
 </Tabs>
 
@@ -74,7 +75,6 @@ for (const record of records) {
     body: record,
   });
 }
-
 ```
 
 </TabItem>
@@ -92,7 +92,6 @@ foreach ($records as $record) {
     $record
   );
 }
-
 ```
 
 </TabItem>

website/docs/api-clients/introduction.md → website/docs/clients/introduction.md

@@ -4,7 +4,7 @@ title: Introduction
 
 # Introduction
 
-This section hosts informations about the [usage of the API clients](https://github.com/algolia/api-clients-automation). For informations regarding the automation and how to contribute, see [the automation page](/docs/automation/introduction).
+This section hosts informations about the [usage of the API clients](https://github.com/algolia/api-clients-automation). For informations regarding the automation and how to contribute, see [the automation page](/docs/contributing/introduction).
 
 ## Repositories
 
@@ -16,9 +16,9 @@ Generated code in production can be find on repository of the clients.
 
 ## Usage
 
-See [the installation](/docs/api-clients/installation) page.
+See [the installation](/docs/clients/installation) page.
 
-You can also check the [playground](/docs/automation/testing/playground) if you'd like to test clients locally.
+You can also check the [playground](/docs/contributing/testing/playground) if you'd like to test clients locally.
 
 ## Feedbacks
 

website/docs/api-clients/migration-guide.mdx → website/docs/clients/migration-guide.mdx

@@ -27,7 +27,7 @@ The changes below are effective on all of the API clients.
 
 The changes below are effective on the selected API client.
 
-For informations regarding the installation of the package, please see [the installation page](/docs/api-clients/installation)
+For informations regarding the installation of the package, please see [the installation page](/docs/clients/installation)
 
 <Tabs
   groupId="language"
@@ -76,7 +76,7 @@ yarn remove algoliasearch
 npm uninstall algoliasearch
 ```
 
-You can continue this guide on [our installation page](/docs/api-clients/installation).
+You can continue this guide on [our installation page](/docs/clients/installation).
 
 ### Importing algoliasearch using ES Modules
 

website/docs/automation/add-new-api-client.md → website/docs/contributing/add-new-api-client.md

@@ -8,7 +8,7 @@ Adding an API client requires a manual steps in order to setup the tooling, gene
 
 :::info
 
-Make sure to first [setup the repository tooling](/docs/automation/setup-repository) to ease your journey!
+Make sure to first [setup the repository tooling](/docs/contributing/setup-repository) to ease your journey!
 
 :::
 
@@ -61,7 +61,7 @@ Below are the options you need to **make sure to define for your client**, other
 | -------------- | :----: | :--------: | :-----------------------------: | :------------------------------------------------------------------------------------------------------------------- |
 | output         | string |   Common   | `path/to/client/client-sources` | The output path of the client.                                                                                       |
 | gitRepoId      | string |   Common   |  `algoliasearch-client-java-2`  | The name of the repository under the Algolia org.                                                                    |
-| packageName    | string |   common   |         `AlgoliaSearch`         | Name of the API package, used in [CTS](/docs/automation/testing/common-test-suite).                                  |
+| packageName    | string |   common   |         `AlgoliaSearch`         | Name of the API package, used in [CTS](/docs/contributing/testing/common-test-suite).                                |
 | packageVersion | string | JavaScript |             `1.2.3`             | The version you'd like to publish the first iteration of the generated client. It will be automatically incremented. |
 
 ### GitHub actions
@@ -88,12 +88,12 @@ You can copy [an existing client caching step](https://github.com/algolia/api-cl
 
 ## 3. Generate new client
 
-> You can find all the commands in the [CLI > clients commands page](/docs/automation/CLI/clients-commands) and [CLI > specs commands page](/docs/automation/CLI/specs-commands).
+> You can find all the commands in the [CLI > clients commands page](/docs/contributing/CLI/clients-commands) and [CLI > specs commands page](/docs/contributing/CLI/specs-commands).
 
 ```bash
 yarn docker generate <languageName> <clientName>
 ```
 
 ## 4. Implementing the Common Test Suite
 
-Clients needs to be tested, you can read more in the [Common Test Suite](/docs/automation/testing/common-test-suite) guide.
+Clients needs to be tested, you can read more in the [Common Test Suite](/docs/contributing/testing/common-test-suite) guide.

website/docs/automation/add-new-language.md → website/docs/contributing/add-new-language.md

@@ -6,7 +6,7 @@ title: Support a new language
 
 :::info
 
-Make sure to first [setup the repository tooling](/docs/automation/setup-repository) to ease your journey!
+Make sure to first [setup the repository tooling](/docs/contributing/setup-repository) to ease your journey!
 
 You will also need to have the [openapi-generator](https://openapi-generator.tech/docs/installation/) installed.
 
@@ -36,7 +36,7 @@ openapi-generator author template -g typescript-node -o templates/javascript/
 
 Add each client in the file [`config/openapitools.json`](https://github.com/algolia/api-clients-automation/blob/main/config/openapitools.json), following the others client structure.
 
-> See [`add a new client`](/docs/automation/add-new-api-client) for informations on how to structure your new client.
+> See [`add a new client`](/docs/contributing/add-new-api-client) for informations on how to structure your new client.
 
 ### Algolia requirements
 
@@ -77,7 +77,7 @@ The retry strategy cannot be generated and needs to be implemented outside of th
 
 Some Algolia clients (search and recommend) targets the default appId host (`${appId}-dsn.algolia.net`, `${appId}.algolia.net`, etc.), while clients like `personalization` have their own regional `host` (`eu` | `us` | `de`).
 
-As the generator does not support reading `servers` in a spec file **yet**, hosts methods and variables are extracted with a custom script and create variables for you to use in the mustache templates, [read more here](/docs/automation/add-new-api-client#generators).
+As the generator does not support reading `servers` in a spec file **yet**, hosts methods and variables are extracted with a custom script and create variables for you to use in the mustache templates, [read more here](/docs/contributing/add-new-api-client#generators).
 
 ### User Agent
 
@@ -114,9 +114,10 @@ The function must be named `addAlgoliaAgent` because of JavaScript exception tha
 ### Dependencies
 
 You can use any dependency you want to create the client, it can be Json parser or HTTP client, but it's important to never expose those dependencies through the client, meaning:
- - a function cannot return an object from a dependency
- - a function cannot accept an object from a dependency as a parameter
- - and so on
+
+- a function cannot return an object from a dependency
+- a function cannot accept an object from a dependency as a parameter
+- and so on
 
 It matters because when a dependency is exposed, a breaking change from our deps can affect the user code while the API client is still working correctly (because they have to use the dependency in their code),
 and that prevent us from upgrading our deps. In some languages it also requires the user to add our internal dependencies to his build system, which is very inconvenient and our clients should always be standalone.

website/docs/contributing/introduction.md

@@ -0,0 +1,32 @@
+---
+title: Introduction
+---
+
+# Introduction
+
+This section hosts informations about the [API clients automation](https://github.com/algolia/api-clients-automation) repository. For informations regarding the clients usage, see [the clients page](/docs/clients/introduction).
+
+## Contributing
+
+To contribute to the repository, make sure to take a look at our guidelines and recommendations:
+
+- [Setup the repository tooling](/docs/contributing/setup-repository): to install our tooling.
+  - CLI commands can be found at [CLI > specs commands](/docs/contributing/CLI/specs-commands), [CLI > clients commands](/docs/contributing/CLI/clients-commands) and [CLI > CTS commands](/docs/contributing/CLI/cts-commands).
+- [Add a new client](/docs/contributing/add-new-api-client): to add a new API spec to generate a client.
+- [Support a new language](/docs/contributing/add-new-language): to add a new supported language to the API clients.
+- [Commit and Pull-request](/docs/contributing/commit-and-pull-request): to see what to commit and send pull-requests.
+- [Release process](/docs/contributing/release-process): to see how to release API clients.
+
+## Testing
+
+Generated clients can be tested via the:
+
+- [Common Test Suite](/docs/contributing/testing/common-test-suite)
+- [Playground](/docs/contributing/testing/playground)
+
+## Feedbacks
+
+To report feedbacks, please use:
+
+- [GitHub issues](https://github.com/algolia/api-clients-automation/issues)
+- [#api-clients-beta-testers slack channel](https://algolia.slack.com/archives/C0341QDM3EG)

website/docs/automation/setup-repository.md → website/docs/contributing/setup-repository.md

@@ -54,11 +54,11 @@ yarn docker:clean
 
 Once you've successfully built and mounted the Docker image, you can now play with the repository! Read our guides on:
 
-- [How to add a new client](/docs/automation/add-new-api-client)
-- [How to add a new language](/docs/automation/add-new-language)
-- [Use CLI specs commands](/docs/automation/CLI/specs-commands)
-- [Use CLI clients commands](/docs/automation/CLI/clients-commands)
-- [Use CLI Common Test Suite commands](/docs/automation/CLI/specs-commands)
+- [How to add a new client](/docs/contributing/add-new-api-client)
+- [How to add a new language](/docs/contributing/add-new-language)
+- [Use CLI specs commands](/docs/contributing/CLI/specs-commands)
+- [Use CLI clients commands](/docs/contributing/CLI/clients-commands)
+- [Use CLI Common Test Suite commands](/docs/contributing/CLI/specs-commands)
 
 ## Troubleshooting
 

website/docs/automation/testing/common-test-suite.md → website/docs/contributing/testing/common-test-suite.md

@@ -11,7 +11,7 @@ It is automaticaly generated for all languages, from a JSON entry point.
 
 Common Test Suite requires all clients to be built.
 
-[CLI commands for the Common Test Suite](/docs/automation/CLI/cts-commands)
+[CLI commands for the Common Test Suite](/docs/contributing/CLI/cts-commands)
 
 :::
 

website/docs/automation/testing/playground.md → website/docs/contributing/testing/playground.md

@@ -8,7 +8,7 @@ All of the existing clients should have an active playground for you to test gen
 
 :::info
 
-Make sure to first [setup the repository tooling](/docs/automation/setup-repository) to ease your journey!
+Make sure to first [setup the repository tooling](/docs/contributing/setup-repository) to ease your journey!
 
 :::
 

website/docusaurus.config.js

@@ -116,12 +116,12 @@ function getSpecsForNavBar() {
             // left
             {
               label: 'Clients',
-              to: 'docs/api-clients/introduction',
+              to: 'docs/clients/introduction',
               position: 'left',
             },
             {
               label: 'Contributing',
-              to: 'docs/automation/introduction',
+              to: 'docs/contributing/introduction',
               position: 'right',
             },
             {

website/sidebars.js

@@ -4,21 +4,21 @@
 const sidebars = {
   // Everything related to the API Clients Automation
   automation: [
-    'automation/introduction',
+    'contributing/introduction',
     {
       type: 'category',
       label: 'Getting Started',
       collapsed: false,
       items: [
-        'automation/setup-repository',
+        'contributing/setup-repository',
         {
           type: 'category',
           label: 'CLI',
           collapsed: false,
           items: [
-            'automation/CLI/specs-commands',
-            'automation/CLI/clients-commands',
-            'automation/CLI/cts-commands',
+            'contributing/CLI/specs-commands',
+            'contributing/CLI/clients-commands',
+            'contributing/CLI/cts-commands',
           ],
         },
       ],
@@ -28,39 +28,39 @@ const sidebars = {
       label: 'Contributing',
       collapsed: false,
       items: [
-        'automation/add-new-api-client',
-        'automation/add-new-language',
+        'contributing/add-new-api-client',
+        'contributing/add-new-language',
         {
           type: 'category',
           label: 'Testing',
           collapsed: false,
           items: [
-            'automation/testing/common-test-suite',
-            'automation/testing/playground',
+            'contributing/testing/common-test-suite',
+            'contributing/testing/playground',
           ],
         },
-        'automation/commit-and-pull-request',
-        'automation/release-process',
+        'contributing/commit-and-pull-request',
+        'contributing/release-process',
       ],
     },
   ],
   // Everything related to the generated clients usage
   clients: [
-    'api-clients/introduction',
+    'clients/introduction',
     {
       type: 'category',
       label: 'Getting Started',
       collapsed: false,
-      items: ['api-clients/installation', 'api-clients/migration-guide'],
+      items: ['clients/installation', 'clients/migration-guide'],
     },
     {
       type: 'category',
       label: 'Guides',
       collapsed: false,
       items: [
-        'api-clients/guides/send-data-to-algolia',
-        'api-clients/guides/filtering-your-search',
-        'api-clients/guides/retrieving-facets',
+        'clients/guides/send-data-to-algolia',
+        'clients/guides/filtering-your-search',
+        'clients/guides/retrieving-facets',
       ],
     },
   ],