docs: generate doc from specs (#92)

Author: shortcuts

README.md

@@ -22,7 +22,7 @@ yarn docker:setup
 
 Build docker image from [Dockerfile](./Dockerfile)
 
-[How to add a new client](./docs/addNewClient.md) | [How to add a new language](./docs/addNewLanguage.md) | [Common Test Suite](./docs/CTS.md) | [Run the playground](./docs/playground.md)
+[How to add a new client](https://api-clients-automation.netlify.app/docs/addNewClient) | [How to add a new language](https://api-clients-automation.netlify.app/docs/addNewLanguage) | [Common Test Suite](https://api-clients-automation.netlify.app/docs/commonTestSuite) | [Run the playground](https://api-clients-automation.netlify.app/docs/playground)
 
 ```bash
 yarn docker:build
@@ -124,7 +124,7 @@ If you want to choose the language and client from a list you can add the `--int
 You can test our generated clients by running:
 
 - The playground [`playground`](./playground) ([Playground README](./docs/playground.md))
-- Tests with our [`Common Test Suite`](./tests/) ([CTS README](./docs/CTS.md)).
+- Tests with our [`Common Test Suite`](./tests/) ([CTS README](./docs/commonTestSuite.md)).
 
 # Troubleshooting
 

docs/changelogs/java.md renamed to changelogs/java.md

@@ -0,0 +1,7 @@
+[build]
+  command="yarn website:build"
+  publish="website/build"
+  ignore="git diff --quiet $COMMIT_REF $CACHED_COMMIT_REF -- website/ specs/bundled/"
+
+[build.environment]
+  YARN_VERSION = "3.1.1"

docs/changelogs/javascript.md renamed to changelogs/javascript.md

@@ -6,7 +6,8 @@
     "playground/javascript/node/",
     "playground/javascript/browser/",
     "scripts/",
-    "tests/output/javascript"
+    "tests/output/javascript",
+    "website/"
   ],
   "scripts": {
     "cli": "yarn workspace scripts ts-node --transpile-only ./index.ts",
@@ -22,7 +23,9 @@
     "scripts:lint": "eslint --ext=ts scripts/",
     "scripts:test": "yarn workspace scripts test",
     "specs:fix": "eslint --ext=yml specs/ --fix",
-    "specs:lint": "eslint --ext=yml specs/$0"
+    "specs:lint": "eslint --ext=yml specs/$0",
+    "website:build": "yarn workspace website build",
+    "website": "yarn workspace website start --host 0.0.0.0"
   },
   "devDependencies": {
     "@openapitools/openapi-generator-cli": "2.4.26",

docs/changelogs/php.md renamed to changelogs/php.md

@@ -15,7 +15,7 @@ export default {
     ].join('\n'),
 
   changelogHeader: `## CHANGELOG`,
-  changelogDescription: `Update the following lines. Once merged, it will be reflected to \`docs/changelogs/*.\``,
+  changelogDescription: `Update the following lines. Once merged, it will be reflected to \`changelogs/*.\``,
 
   approvalHeader: `## Approval`,
   approved: APPROVED,

netlify.toml

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

package.json

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

scripts/release/text.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line import/no-commonjs
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/.gitignore

@@ -1,24 +1,28 @@
-# How to add a new client
+---
+title: Add a new client
+---
+
+# Add a new client
 
 Adding a client requires a few manual steps in order to setup the tooling, generation scripts and properly generate the code. We recommend getting inspirations from existing clients such as `javascript-recommend`.
 
-> See [README](../README.md) to [`setup the repository tooling`](../README.md#setup-repository-tooling) and [`setup dev environment`](../README.md#setup-dev-environment).
+> See the [Setup repository guide](/docs/setupRepository) to [`setup the repository tooling`](/docs/setupRepository#setup-the-repository-tooling).
 
 ## 1. Writing specs
 
-We recommend to have a look at [existing spec files](../specs/). The `bundled` folder is automatically generated, manual changes shouldn't be done in these files.
+We recommend to have a look at [existing spec files](https://github.com/algolia/api-clients-automation/blob/main/specs/). The `bundled` folder is automatically generated, manual changes shouldn't be done in these files.
 
-### [common spec folder](../specs/common/)
+### [common spec folder](https://github.com/algolia/api-clients-automation/blob/main/specs/common/)
 
 Properties that are common to Algolia or used in multiple clients.
 
 ### `<clientName>` spec folder
 
-> Example with the [search client spec](../specs/search/)
+> Example with the [search client spec](https://github.com/algolia/api-clients-automation/blob/main/specs/search/)
 
 #### `spec.yml` file
 
-This file is the entry point of the client spec, it contains `servers`, `paths` and other specific imformations of the API. We recommend to copy an existing [`spec.yml` file](../specs/search/spec.yml) to get started.
+This file is the entry point of the client spec, it contains `servers`, `paths` and other specific imformations of the API. We recommend to copy an existing [`spec.yml` file](https://github.com/algolia/api-clients-automation/blob/main/specs/search/spec.yml) to get started.
 
 #### `<clientName>`/common folder
 
@@ -38,11 +42,11 @@ Path definition of the paths defined in the [spec file](#specyml-file)
 
 ## 2. Configuring the environment
 
-After setting up the dev environment from [README](../README.md) and [writing your spec files](#1-writing-specs), you need to update the configuration files to properly generate clients that are maintainable.
+After setting up the dev environment from [README](/docs/setupRepository) and [writing your spec files](#1-writing-specs), you need to update the configuration files to properly generate clients that are maintainable.
 
 ### Generation config
 
-[openapitools.json](../openapitools.json) hosts the configuration of all of the generated clients with their available languages.
+[openapitools.json](https://github.com/algolia/api-clients-automation/blob/main/openapitools.json) hosts the configuration of all of the generated clients with their available languages.
 
 #### `generators`
 
@@ -60,19 +64,19 @@ You can copy an existing object of a client and replace the `<clientName>` value
 | apiName            | string  | JavaScript |            `search`             | The lowercase name of the exported API.                                                                                                         |
 | capitalizedApiName | string  | JavaScript |            `Search`             | The capitalized name of the exported API.                                                                                                       |
 | 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.                            |
-| packageName        | string  |   common   |         `AlgoliaSearch`         | Name of the API package, used in [CTS](./CTS.md).                                                                                               |
+| packageName        | string  |   common   |         `AlgoliaSearch`         | Name of the API package, used in [CTS](/docs/commonTestSuite).                                                                                  |
 | hasRegionalHost    | boolean |   common   |             `false`             | Automatically guessed from `servers` in spec. `undefined` implies that hosts used will required the `appId`, regional hosts are used otherwise. |
 | isDeHost           | boolean |   common   |             `false`             | Automatically guessed from `servers` in spec. `undefined` implies that `eu` is the regional host, `de` otherwise.                               |
 | host               | string  |   common   |            `crawler`            | Automatically guessed from `servers` in spec.                                                                                                   |
 | topLevelDomain     | string  |   common   |              `io`               | Automatically guessed from `servers` in spec.                                                                                                   |
 
 ### GitHub actions
 
-The built clients are cached with the [Cache GitHub Action](../.github/actions/cache/action.yml) to avoid unnecessary CI tasks.
+The built clients are cached with the [Cache GitHub Action](https://github.com/algolia/api-clients-automation/blob/main/.github/actions/cache/action.yml) to avoid unnecessary CI tasks.
 
 > TODO: Automate this step
 
-You can copy [an existing client caching step](../.github/actions/cache/action.yml) or edit the following example:
+You can copy [an existing client caching step](https://github.com/algolia/api-clients-automation/blob/main/.github/actions/cache/action.yml) or edit the following example:
 
 ```yaml
 - name: Restore built <LANGUAGE> <CLIENT_NAME> client
@@ -85,12 +89,12 @@ You can copy [an existing client caching step](../.github/actions/cache/action.y
 
 ## 3. Generate new client
 
-> You can find more commands in the [README](../README.md#generate-all-clients).
+> You can find more commands in the [CLI > generation commands page](/docs/generationCommands) and [CLI > specs commands page](/docs/specsCommands).
 
 ```bash
 yarn docker generate <languageName> <clientName>
 ```
 
 ## 4. Implementing the Common Test Suite
 
-See [CTS.md](./CTS.md) for more informations.
+See [CTS.md](/docs/commonTestSuite) for more informations.

website/README.md

@@ -1,8 +1,12 @@
-# How to add support of a new language
+---
+title: Support a new language
+---
+
+# Support a new language
 
 This repository leverages [openapi-generator](https://openapi-generator.tech/) to generate API clients.
 
-> See [README](../README.md) to [`setup the repository tooling`](../README.md#setup-repository-tooling) and [`setup dev environment`](../README.md#setup-dev-environment).
+> See the [Setup repository guide](/docs/setupRepository) to [`setup the repository tooling`](/docs/setupRepository#setup-the-repository-tooling).
 
 > If not done already, [install openapi-generator](https://openapi-generator.tech/docs/installation/)
 
@@ -26,9 +30,9 @@ openapi-generator author template -g typescript-node -o templates/javascript/
 
 ## Update the generator config
 
-Add each client in the file [`openapitools.json`](../openapitools.json), following the others client structure.
+Add each client in the file [`openapitools.json`](https://github.com/algolia/api-clients-automation/blob/main/openapitools.json), following the others client structure.
 
-> See [How to add a new client](./addNewClient.md) for informations regarding this file
+> See [`add a new client`](/docs/addNewClient) for informations regarding this file
 
 ### Algolia requirements
 
@@ -62,7 +66,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, hosts methods and variables are extracted with a custom script and create variables for you to use in the mustache templates, [read more here](./addNewClient.md#generators).
+As the generator does not support reading `servers` in a spec file, 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/addNewClient#generators).
 
 ### Requesters
 

website/babel.config.js

@@ -1,3 +1,7 @@
+---
+title: Common Test Suite
+---
+
 # Common Test Suite
 
 The CTS aims at ensuring minimal working operation for the API clients, by comparing the request formed by sample parameters.

docs/addNewClient.md renamed to website/docs/addNewClient.md

@@ -0,0 +1,42 @@
+---
+title: Generation commands
+---
+
+# CLI generation commands
+
+## Usage
+
+```bash
+yarn docker generate <language | all> <client | all>
+```
+
+### Available options
+
+| Option      | Command           | Description                                                   |
+| ----------- | :---------------- | :------------------------------------------------------------ |
+| verbose     | -v, --verbose     | Make the process verbose, display logs from third party tools |
+| interactive | -i, --interactive | Open prompt to query parameters                               |
+
+## Generate all clients for all support languages
+
+```bash
+yarn docker generate
+```
+
+### Generate specific client for specific language
+
+```bash
+yarn docker generate java sources
+```
+
+## Build all clients for all support languages
+
+```bash
+yarn docker build clients
+```
+
+### Build specific client for specific language
+
+```bash
+yarn docker build clients javascript recommend
+```

docs/addNewLanguage.md renamed to website/docs/addNewLanguage.md

@@ -0,0 +1,97 @@
+---
+title: Getting started
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+## Installation
+
+To get started, you first need to install `algoliasearch` (or any other available API client package)
+
+```bash
+yarn add @experimental-api-clients-automation/algoliasearch
+```
+
+Or use a specific package to reduce bundle size:
+
+```bash
+yarn add @experimental-api-clients-automation/client-search
+```
+
+You can find the full list of available packages [here](https://www.npmjs.com/org/experimental-api-clients-automation).
+
+### Without a package manager
+
+Add the JavaScript to your `<head>`
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@experimental-api-clients-automation/[email protected]/dist/algoliasearch.umd.browser.js"></script>
+```
+
+## Using the client
+
+Then you need to import the correct package, depending on your choice:
+
+```js
+import { algoliasearch } from 'algoliasearch';
+
+const client = algoliasearch(appId, apiKey);
+
+// And access analytics or personalization client
+const analyticsClient = client.initAnalytics(analyticsAppId, analyticsApiKey);
+const personalizationCilent = client.initPersonalization(personalizationAppId, personalizationApiKey, 'eu');
+```
+
+```js
+import { searchApi } from '@algolia/client-search';
+
+const client = searchApi(appId, apiKey);
+```
+
+It is possible to customize the client by passing optional parameters:
+
+```js
+const client = searchApi(appId, apiKey, {
+    requester: customRequester(),
+    hosts: [{
+        url: 'my.custom.host.net',
+        accept: 'read',
+        protocol: 'https',
+    }]
+})
+```
+
+Once the client is setup, you can enjoy all of Algolia API !
+
+```js
+const res = await client.search({
+    indexName: 'my-index',
+    searchParams: { query: 'words to query' },
+});
+
+console.log('Search result', res.hits);
+```
+
+
+Or with the `personalization` client
+
+```js
+const res = await personalizationCilent.getUserTokenProfile({
+    userToken: 'token',
+});
+
+console.log('User scores', res.scores);
+```
+
+</TabItem>
+</Tabs>