diff --git a/scripts/cli/index.ts b/scripts/cli/index.ts index 65c2b16f7e8..15f9394c487 100644 --- a/scripts/cli/index.ts +++ b/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 }) => { diff --git a/website/docs/CLI/build-commands.md b/website/docs/CLI/build-commands.md new file mode 100644 index 00000000000..cff68373b18 --- /dev/null +++ b/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 +``` + +### 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 +``` + +### 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 +``` diff --git a/website/docs/CLI/cts-commands.md b/website/docs/CLI/cts-commands.md index d0a92f3368f..3ac58758dee 100644 --- a/website/docs/CLI/cts-commands.md +++ b/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. diff --git a/website/docs/CLI/clients-commands.md b/website/docs/CLI/generate-commands.md similarity index 85% rename from website/docs/CLI/clients-commands.md rename to website/docs/CLI/generate-commands.md index f46b7172798..0327fbc1d69 100644 --- a/website/docs/CLI/clients-commands.md +++ b/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 diff --git a/website/docs/CLI/release-commands.md b/website/docs/CLI/release-commands.md index b6b34526c34..24f347ee4d6 100644 --- a/website/docs/CLI/release-commands.md +++ b/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 diff --git a/website/docs/CLI/specs-commands.md b/website/docs/CLI/specs-commands.md deleted file mode 100644 index 7fd06e20424..00000000000 --- a/website/docs/CLI/specs-commands.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Specs commands ---- - -# Specs commands - -The Specs commands are used to [`build`](#build), [`lint`](#lint) and validate the REST API specs. - -## Usage - -> `client` defaults to `all` - -> The `client` parameter is variadic, you can pass multiple `client` name - -```bash -apic build specs -``` - -### 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 | - -## Build - -### 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 -yarn specs:lint search -``` diff --git a/website/docs/add-new-api-client.md b/website/docs/add-new-api-client.md index 94834a2cb75..fc6a9cb554d 100644 --- a/website/docs/add-new-api-client.md +++ b/website/docs/add-new-api-client.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 diff --git a/website/docs/introduction.md b/website/docs/introduction.md index 3354b92b462..daeea613fa2 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.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. diff --git a/website/docs/setup-repository.md b/website/docs/setup-repository.md index 7860dccb25c..c3749fb5b46 100644 --- a/website/docs/setup-repository.md +++ b/website/docs/setup-repository.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 diff --git a/website/docs/testing/common-test-suite.md b/website/docs/testing/common-test-suite.md index 843eddd8298..28e8e9b0d7a 100644 --- a/website/docs/testing/common-test-suite.md +++ b/website/docs/testing/common-test-suite.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) ::: diff --git a/website/sidebars.js b/website/sidebars.js index 92a44a6bf7d..cb028f4e654 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -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'], }, ], },