docs: generate doc from specs

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/CTS) | [Run the playground](https://api-clients-automation.netlify.app/docs/playground)
 
 ```bash
 yarn docker:build

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/"
+
+[build.environment]
+  YARN_VERSION = "3.2.0"

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

@@ -6,7 +6,8 @@
     "playground/javascript/node/",
     "playground/javascript/browser/",
     "tests/",
-    "scripts/"
+    "scripts/",
+    "website/"
   ],
   "scripts": {
     "build:clients": "./scripts/multiplexer.sh ${2:-nonverbose} ./scripts/builds/clients.sh ${0:-all} ${1:-all}",
@@ -30,7 +31,9 @@
     "specs:fix": "eslint --ext=yml specs/ --fix",
     "specs:lint": "eslint --ext=yml specs/$0",
     "github-actions:lint": "eslint --ext=yml .github/",
-    "release": "yarn workspace scripts createReleaseIssue"
+    "release": "yarn workspace scripts createReleaseIssue",
+    "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

@@ -92,7 +92,7 @@ fs.writeFileSync(
 // update changelogs
 new Set([...Object.keys(versionsToRelease), ...langsToUpdateRepo]).forEach(
   (lang) => {
-    const filePath = path.resolve(ROOT_DIR, `docs/changelogs/${lang}.md`);
+    const filePath = path.resolve(ROOT_DIR, `changelogs/${lang}.md`);
     const header = versionsToRelease[lang!]
       ? `## ${versionsToRelease[lang!].next}`
       : `## ${new Date().toISOString().split('T')[0]}`;

netlify.toml

@@ -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,

package.json

@@ -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*

scripts/release/process-release.ts

@@ -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,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.

website/README.md

@@ -1,24 +1,28 @@
+---
+title: How to add a new client?
+---
+
 # How to 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 [README](/docs/setupRepository) to [`setup the repository tooling`](/docs/setupRepository#setup-repository-tooling) and [`setup dev environment`](/docs/setupRepository#setup-dev-environment).
 
 ## 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/Dockerfile/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/Dockerfile/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/Dockerfile/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/Dockerfile/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/Dockerfile/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/CTS).                                                                                              |
 | 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/Dockerfile/.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/Dockerfile/.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 [README](/docs/setupRepository#generate-all-clients).
 
 ```bash
 yarn docker generate <languageName> <clientName>
 ```
 
 ## 4. Implementing the Common Test Suite
 
-See [CTS.md](./CTS.md) for more informations.
+See [CTS.md](/docs/CTS) for more informations.

website/babel.config.js

@@ -1,8 +1,12 @@
+---
+title: How to add a new supported language?
+---
+
 # How to add support of 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 [README](/docs/setupRepository) to [`setup the repository tooling`](/docs/setupRepository#setup-repository-tooling) and [`setup dev environment`](/docs/setupRepository#setup-dev-environment).
 
 > 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/Dockerfileopenapitools.json), following the others client structure.
 
-> See [How to add a new client](./addNewClient.md) for informations regarding this file
+> See [How to 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
 

docs/CTS.md renamed to website/docs/CTS.md

@@ -0,0 +1,23 @@
+---
+title: Introduction
+---
+
+# Introduction
+
+API Clients Automation by Algolia
+
+## Specs doc
+
+- [A/B Testing specs](/specs/abtesting)
+- [analytics specs](/specs/analytics)
+- [insights specs](/specs/insights)
+- [personalization specs](/specs/personalization)
+- [query-suggestions specs](/specs/query-suggestions)
+- [recommend specs](/specs/recommend)
+- [search specs](/specs/search)
+- [sources specs](/specs/sources)
+- [predict specs](/specs/predict)
+
+## Repository
+
+[API Clients Automation](https://github.com/algolia/api-clients-automation)

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

@@ -1,3 +1,7 @@
+---
+title: Playground
+---
+
 # Playground
 
 All of the existing clients should have an active playground for you to test generated clients, if it's not the case, consider contributing or letting us know!
@@ -24,5 +28,5 @@ yarn docker playground java search
 
 To add a new supported language to the playground, you need to:
 
-- Create a new folder with your `<languageName>` in [the playground folder](../playground/)
-- Edit the [playground script](../scripts/playground.sh) with the command to run it.
+- Create a new folder with your `<languageName>` in [the playground folder](https://github.com/algolia/api-clients-automation/blob/main/playground)
+- Edit the [playground script](https://github.com/algolia/api-clients-automation/blob/main/scripts/playground.sh) with the command to run it.