docs: update contribution guides [skip-bc] (#4051)

Author: shortcuts

scripts/cli/index.ts

@@ -34,10 +34,6 @@ const flags = {
     flag: '-v, --verbose',
     description: 'make the generation verbose',
   },
-  skipCache: {
-    flag: '-s, --skip-cache',
-    description: 'skip cache checking to force building specs',
-  },
 };
 
 program.name('cli');
@@ -141,7 +137,7 @@ buildCommand
   .description('Build a specified spec')
   .addArgument(args.clients)
   .option(flags.verbose.flag, flags.verbose.description)
-  .option(flags.skipCache.flag, flags.skipCache.description)
+  .option('-s, --skip-cache', 'skip cache checking to force building specs')
   .option('-json, --output-json', 'outputs the spec in JSON instead of yml')
   .option('-d, --docs', 'generates the doc specs with the code snippets')
   .action(async (clientArg: string[], { verbose, skipCache, outputJson, docs }) => {

website/docs/CLI/build-commands.md

@@ -0,0 +1,107 @@
+---
+title: Build commands
+---
+
+# Build commands
+
+:::info
+
+You can use `yarn cli` as a drop in replacement for `apic`.
+
+:::
+
+The Build commands are used to [`build`](#build) API specs, clients, playground, snippets and guides.
+
+## Usage for specs
+
+> `client` defaults to `all`
+
+> The `client` parameter is variadic, you can pass multiple `client` name
+
+```bash
+apic build specs <client... | all>
+```
+
+### Available options
+
+| Option     | Command          | Description                                                    |
+| ---------- | :--------------- | :------------------------------------------------------------- |
+| verbose    | -v, --verbose    | Make the process verbose, display logs from third party tools  |
+| skip cache | -s, --skip-cache | Skip cache checking to force building specs                    |
+| docs       | -d, --docs       | Builds the specs for the Algolia doc, which embeds the snippets|
+
+## Build specs
+
+### Build all specs
+
+```bash
+apic build specs
+```
+
+### Build specific spec
+
+```bash
+apic build specs recommend
+```
+
+### Build many spec
+
+```bash
+apic build specs recommend search ingestion
+```
+
+## Lint
+
+### Fix specs
+
+> Automatically done when building specs
+
+```bash
+yarn specs:fix
+```
+
+### Check specs
+
+If you just want to check the format (not override the files)
+
+```bash
+yarn specs:lint search
+```
+
+## Usage for clients, playground, snippets and guides
+
+> `language` and `client` defaults to `all`
+
+> The `client` parameter is variadic, you can pass multiple `client` name
+
+> scope is one of: `clients` | `playground` | `snippets` | `guides`
+
+```bash
+apic build <scope> <language | all> <client... | all>
+```
+
+### Available options
+
+| Option  | Command       | Description                                                   |
+| ------- | :------------ | :------------------------------------------------------------ |
+| verbose | -v, --verbose | Make the process verbose, display logs from third party tools |
+
+## Build
+
+### Build all clients for all supported languages
+
+```bash
+apic build clients
+```
+
+### Build playground for specific language
+
+```bash
+apic build playground javascript recommend
+```
+
+### Build many snippets for specific language
+
+```bash
+apic build snippets java insights recommend search
+```

website/docs/CLI/cts-commands.md

@@ -8,6 +8,8 @@ title: Common Test Suite commands
 
 Common Test Suite requires all clients to be built.
 
+You can use `yarn cli` as a drop in replacement for `apic`.
+
 :::
 
 The Common Test Suite commands are used to [`generate`](#generate) and [`run`](#run) tests.

website/docs/CLI/clients-commands.md renamed to website/docs/CLI/generate-commands.md

@@ -1,10 +1,16 @@
 ---
-title: Clients commands
+title: Generate commands
 ---
 
-# Clients commands
+# Generate commands
 
-The Clients commands are used to [`generate`](#generate) and [`build`](#build) API clients.
+:::info
+
+You can use `yarn cli` as a drop in replacement for `apic`.
+
+:::
+
+The Generate commands are used to [`generate`](#generate) API clients.
 
 ## Usage
 

website/docs/CLI/release-commands.md

@@ -4,6 +4,12 @@ title: Release commands
 
 # Release commands
 
+:::info
+
+You can use `yarn cli` as a drop in replacement for `apic`.
+
+:::
+
 The Release commands are used to release every, or a subset of API clients.
 
 ## Usage

website/docs/CLI/specs-commands.md

@@ -152,22 +152,28 @@ The file [`config/clients.config.json`](https://github.com/algolia/api-clients-a
 
 The following fields are required:
 
-| Option               | Description                                                                                       |
-| -------------------- | ------------------------------------------------------------------------------------------------- |
-| `folder`             | Path to the parent folder of every client for this language.                                      |
-| `gitRepoId`          | Name of the repository for this API client.                                                       |
-| `packageVersion`     | Initial version number to publish for the generated client. It will be automatically incremented. |
-| `modelFolder`        | Path to the `model` folder that will host the generated code.                                     |
-| `apiFolder`          | Path to the `api` folder that will host the generated code.                                       |
-| `tests.extension`    | Test file extension, such as `.test.java` or `_test.py`                                           |
-| `tests.outputFolder` | Path to the folder that holds the tests for this language, such as `tests/`                       |
+| Option                 | Description                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `clients`              | The clients to generate, either a list of string (matching the api name), or see below            |
+| `clients.name`         | The name of the client to generate (matching the API name)                                        |
+| `clients.output`       | The output folder                                                                                 |
+| `folder`               | Path to the parent folder of every client for this language.                                      |
+| `gitRepoId`            | Name of the repository for this API client.                                                       |
+| `packageVersion`       | Initial version number to publish for the generated client. It will be automatically incremented. |
+| `modelFolder`          | Path to the `model` folder that will host the generated code.                                     |
+| `apiFolder`            | Path to the `api` folder that will host the generated code.                                       |
+| `dockerImage`          | The name of the docker image that runs this client `apic_base` | `apic_ruby` | `apic_swift`       |
+| `tests.extension`      | Test file extension, such as `.test.java` or `_test.py`                                           |
+| `tests.outputFolder`   | Path to the folder that holds the tests for this language, such as `tests/`                       |
+| `snippets.extension`   | Snippet file extension, such as `.java` or `.py`                                                  |
+| `snippets.outputFolder`| Path to the folder that holds the snippets for this language, such as `lib/`                      |
 
 ## 3. Generate the client
 
 Use the CLI to generate the clients:
 
-- [Commands for working with specs](./CLI/specs-commands.md)
-- [Commands for working with clients](./CLI/clients-commands.md)
+- [Commands for working with specs](./CLI/build-commands.md)
+- [Commands for working with clients](./CLI/generate-commands.md)
 
 ## 4. Add tests with the Common Test Suite
 

website/docs/add-new-api-client.md

@@ -11,7 +11,7 @@ This section hosts informations about the [API clients automation](https://githu
 To contribute to the repository, make sure to take a look at our guidelines and recommendations:
 
 - [Setup the repository tooling](/docs/setup-repository): to install our tooling.
-  - CLI commands can be found at [CLI > specs commands](/docs/CLI/specs-commands), [CLI > clients commands](/docs/CLI/clients-commands) and [CLI > CTS commands](/docs/CLI/cts-commands).
+  - CLI commands can be found at [CLI > build commands](/docs/CLI/build-commands), [CLI > generate commands](/docs/CLI/generate-commands) and [CLI > CTS commands](/docs/CLI/cts-commands).
 - [Add a new client](/docs/add-new-api-client): to add a new API spec to generate a client.
 - [Support a new language](/docs/add-new-language): to add a new supported language to the API clients.
 - [Commit and Pull-request](/docs/commit-and-pull-request): to see what to commit and send pull-requests.

website/docs/introduction.md

@@ -6,7 +6,9 @@ title: Setup repository
 
 :::info
 
-Make sure to have Docker installed so you don't have to install the tooling for every API clients. [Installation guide](https://docs.docker.com/desktop/mac/install/)
+Make sure to have:
+- [Docker installed so you don't have to install the tooling for every API clients](https://docs.docker.com/desktop/mac/install/)
+- [jq because it's nice](https://jqlang.github.io/jq/download/)
 
 :::
 
@@ -18,28 +20,19 @@ nvm use && yarn
 
 ## Mounting the docker images
 
-```bash
-yarn docker:setup
-```
-
-### Docker
-
-#### Build
-
-We use 1 docker image per language to simplify the build, and reuse them on the CI.
-There is one base image containing node, java, scala and kotlin, located in [scripts/docker/Dockerfile](https://github.com/algolia/api-clients-automation/blob/main/scripts/docker/Dockerfile)
+We use multiple docker images to simplify the build. There is [one base image](https://github.com/algolia/api-clients-automation/blob/main/scripts/docker/Dockerfile.base) that contains everything except [swift](https://github.com/algolia/api-clients-automation/blob/main/scripts/docker/Dockerfile.swift) and [ruby](https://github.com/algolia/api-clients-automation/blob/main/scripts/docker/Dockerfile.ruby), they have their own Dockerfile
 
 ```bash
 yarn docker:setup
 ```
 
-:::caution
+## Tooling 
 
-The swift images takes a really long time to build (~5 minutes) because of swift-format, but it's only needed when you want to format swift.
+:::info
 
-:::
+This step is optional, using `yarn cli ...` should work perfectly as well.
 
-## Tooling
+:::
 
 Install the CLI tool by following the instructions at the top of [scripts/install.sh](https://github.com/algolia/api-clients-automation/blob/main/scripts/install.sh) to acces `apic` from your terminal, with bash autocompletion.
 You can run `apic help` to check if it's working properly.
@@ -58,10 +51,10 @@ Once you've successfully built and mounted the Docker image, you can now play wi
 
 - [How to add a new client](/docs/add-new-api-client)
 - [How to add a new language](/docs/add-new-language)
-- [Use CLI specs commands](/docs/CLI/specs-commands)
-- [Use CLI clients commands](/docs/CLI/clients-commands)
+- [Use CLI specs commands](/docs/CLI/build-commands)
+- [Use CLI clients commands](/docs/CLI/generate-commands)
 - [Use CLI release commands](/docs/CLI/release-commands)
-- [Use CLI Common Test Suite commands](/docs/CLI/specs-commands)
+- [Use CLI Common Test Suite commands](/docs/CLI/build-commands)
 
 ## Troubleshooting
 

website/docs/setup-repository.md

@@ -9,7 +9,7 @@ It is automatically generated for all languages from JSON files and ensure prope
 
 :::info
 
-While some clients can run tests from source, languages like Java or JavaScript and other requires clients to be built, see [CLI > clients commands page](/docs/CLI/clients-commands)
+While some clients can run tests from source, languages like Java or JavaScript and other requires clients to be built, see [CLI > generate commands page](/docs/CLI/generate-commands)
 
 :::
 

website/docs/testing/common-test-suite.md

@@ -15,7 +15,7 @@ const sidebars = {
           type: 'category',
           label: 'CLI',
           collapsed: false,
-          items: ['CLI/specs-commands', 'CLI/clients-commands', 'CLI/release-commands', 'CLI/cts-commands'],
+          items: ['CLI/generate-commands', 'CLI/build-commands', 'CLI/cts-commands', 'CLI/release-commands'],
         },
       ],
     },