Skip to content

Commit 823799f

Browse files
authored
docs: generate doc from specs (#92)
1 parent fe2120b commit 823799f

31 files changed

+8650
-296
lines changed

README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ yarn docker:setup
2222

2323
Build docker image from [Dockerfile](./Dockerfile)
2424

25-
[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)
25+
[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)
2626

2727
```bash
2828
yarn docker:build
@@ -124,7 +124,7 @@ If you want to choose the language and client from a list you can add the `--int
124124
You can test our generated clients by running:
125125

126126
- The playground [`playground`](./playground) ([Playground README](./docs/playground.md))
127-
- Tests with our [`Common Test Suite`](./tests/) ([CTS README](./docs/CTS.md)).
127+
- Tests with our [`Common Test Suite`](./tests/) ([CTS README](./docs/commonTestSuite.md)).
128128

129129
# Troubleshooting
130130

File renamed without changes.
File renamed without changes.
File renamed without changes.

netlify.toml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[build]
2+
command="yarn website:build"
3+
publish="website/build"
4+
ignore="git diff --quiet $COMMIT_REF $CACHED_COMMIT_REF -- website/ specs/bundled/"
5+
6+
[build.environment]
7+
YARN_VERSION = "3.1.1"

package.json

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
"playground/javascript/node/",
77
"playground/javascript/browser/",
88
"scripts/",
9-
"tests/output/javascript"
9+
"tests/output/javascript",
10+
"website/"
1011
],
1112
"scripts": {
1213
"cli": "yarn workspace scripts ts-node --transpile-only ./index.ts",
@@ -22,7 +23,9 @@
2223
"scripts:lint": "eslint --ext=ts scripts/",
2324
"scripts:test": "yarn workspace scripts test",
2425
"specs:fix": "eslint --ext=yml specs/ --fix",
25-
"specs:lint": "eslint --ext=yml specs/$0"
26+
"specs:lint": "eslint --ext=yml specs/$0",
27+
"website:build": "yarn workspace website build",
28+
"website": "yarn workspace website start --host 0.0.0.0"
2629
},
2730
"devDependencies": {
2831
"@openapitools/openapi-generator-cli": "2.4.26",

scripts/release/text.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ export default {
1515
].join('\n'),
1616

1717
changelogHeader: `## CHANGELOG`,
18-
changelogDescription: `Update the following lines. Once merged, it will be reflected to \`docs/changelogs/*.\``,
18+
changelogDescription: `Update the following lines. Once merged, it will be reflected to \`changelogs/*.\``,
1919

2020
approvalHeader: `## Approval`,
2121
approved: APPROVED,

website/.gitignore

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

website/README.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
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.

website/babel.config.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// eslint-disable-next-line import/no-commonjs
2+
module.exports = {
3+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
4+
};

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

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,28 @@
1-
# How to add a new client
1+
---
2+
title: Add a new client
3+
---
4+
5+
# Add a new client
26

37
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`.
48

5-
> See [README](../README.md) to [`setup the repository tooling`](../README.md#setup-repository-tooling) and [`setup dev environment`](../README.md#setup-dev-environment).
9+
> See the [Setup repository guide](/docs/setupRepository) to [`setup the repository tooling`](/docs/setupRepository#setup-the-repository-tooling).
610
711
## 1. Writing specs
812

9-
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.
13+
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.
1014

11-
### [common spec folder](../specs/common/)
15+
### [common spec folder](https://github.com/algolia/api-clients-automation/blob/main/specs/common/)
1216

1317
Properties that are common to Algolia or used in multiple clients.
1418

1519
### `<clientName>` spec folder
1620

17-
> Example with the [search client spec](../specs/search/)
21+
> Example with the [search client spec](https://github.com/algolia/api-clients-automation/blob/main/specs/search/)
1822
1923
#### `spec.yml` file
2024

21-
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.
25+
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.
2226

2327
#### `<clientName>`/common folder
2428

@@ -38,11 +42,11 @@ Path definition of the paths defined in the [spec file](#specyml-file)
3842

3943
## 2. Configuring the environment
4044

41-
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.
45+
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.
4246

4347
### Generation config
4448

45-
[openapitools.json](../openapitools.json) hosts the configuration of all of the generated clients with their available languages.
49+
[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.
4650

4751
#### `generators`
4852

@@ -60,19 +64,19 @@ You can copy an existing object of a client and replace the `<clientName>` value
6064
| apiName | string | JavaScript | `search` | The lowercase name of the exported API. |
6165
| capitalizedApiName | string | JavaScript | `Search` | The capitalized name of the exported API. |
6266
| 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. |
63-
| packageName | string | common | `AlgoliaSearch` | Name of the API package, used in [CTS](./CTS.md). |
67+
| packageName | string | common | `AlgoliaSearch` | Name of the API package, used in [CTS](/docs/commonTestSuite). |
6468
| hasRegionalHost | boolean | common | `false` | Automatically guessed from `servers` in spec. `undefined` implies that hosts used will required the `appId`, regional hosts are used otherwise. |
6569
| isDeHost | boolean | common | `false` | Automatically guessed from `servers` in spec. `undefined` implies that `eu` is the regional host, `de` otherwise. |
6670
| host | string | common | `crawler` | Automatically guessed from `servers` in spec. |
6771
| topLevelDomain | string | common | `io` | Automatically guessed from `servers` in spec. |
6872

6973
### GitHub actions
7074

71-
The built clients are cached with the [Cache GitHub Action](../.github/actions/cache/action.yml) to avoid unnecessary CI tasks.
75+
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.
7276

7377
> TODO: Automate this step
7478
75-
You can copy [an existing client caching step](../.github/actions/cache/action.yml) or edit the following example:
79+
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:
7680

7781
```yaml
7882
- name: Restore built <LANGUAGE> <CLIENT_NAME> client
@@ -85,12 +89,12 @@ You can copy [an existing client caching step](../.github/actions/cache/action.y
8589
8690
## 3. Generate new client
8791
88-
> You can find more commands in the [README](../README.md#generate-all-clients).
92+
> You can find more commands in the [CLI > generation commands page](/docs/generationCommands) and [CLI > specs commands page](/docs/specsCommands).
8993
9094
```bash
9195
yarn docker generate <languageName> <clientName>
9296
```
9397

9498
## 4. Implementing the Common Test Suite
9599

96-
See [CTS.md](./CTS.md) for more informations.
100+
See [CTS.md](/docs/commonTestSuite) for more informations.

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

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1-
# How to add support of a new language
1+
---
2+
title: Support a new language
3+
---
4+
5+
# Support a new language
26

37
This repository leverages [openapi-generator](https://openapi-generator.tech/) to generate API clients.
48

5-
> See [README](../README.md) to [`setup the repository tooling`](../README.md#setup-repository-tooling) and [`setup dev environment`](../README.md#setup-dev-environment).
9+
> See the [Setup repository guide](/docs/setupRepository) to [`setup the repository tooling`](/docs/setupRepository#setup-the-repository-tooling).
610
711
> If not done already, [install openapi-generator](https://openapi-generator.tech/docs/installation/)
812
@@ -26,9 +30,9 @@ openapi-generator author template -g typescript-node -o templates/javascript/
2630

2731
## Update the generator config
2832

29-
Add each client in the file [`openapitools.json`](../openapitools.json), following the others client structure.
33+
Add each client in the file [`openapitools.json`](https://github.com/algolia/api-clients-automation/blob/main/openapitools.json), following the others client structure.
3034

31-
> See [How to add a new client](./addNewClient.md) for informations regarding this file
35+
> See [`add a new client`](/docs/addNewClient) for informations regarding this file
3236
3337
### Algolia requirements
3438

@@ -62,7 +66,7 @@ The retry strategy cannot be generated and needs to be implemented outside of th
6266

6367
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`).
6468

65-
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).
69+
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).
6670

6771
### Requesters
6872

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
title: Common Test Suite
3+
---
4+
15
# Common Test Suite
26

37
The CTS aims at ensuring minimal working operation for the API clients, by comparing the request formed by sample parameters.

website/docs/generationCommands.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Generation commands
3+
---
4+
5+
# CLI generation commands
6+
7+
## Usage
8+
9+
```bash
10+
yarn docker generate <language | all> <client | all>
11+
```
12+
13+
### Available options
14+
15+
| Option | Command | Description |
16+
| ----------- | :---------------- | :------------------------------------------------------------ |
17+
| verbose | -v, --verbose | Make the process verbose, display logs from third party tools |
18+
| interactive | -i, --interactive | Open prompt to query parameters |
19+
20+
## Generate all clients for all support languages
21+
22+
```bash
23+
yarn docker generate
24+
```
25+
26+
### Generate specific client for specific language
27+
28+
```bash
29+
yarn docker generate java sources
30+
```
31+
32+
## Build all clients for all support languages
33+
34+
```bash
35+
yarn docker build clients
36+
```
37+
38+
### Build specific client for specific language
39+
40+
```bash
41+
yarn docker build clients javascript recommend
42+
```

website/docs/gettingStarted.mdx

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Getting started
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
<Tabs
9+
groupId="language"
10+
defaultValue="js"
11+
values={[
12+
{ label: 'JavaScript', value: 'js', }
13+
]
14+
}>
15+
<TabItem value="js">
16+
17+
## Installation
18+
19+
To get started, you first need to install `algoliasearch` (or any other available API client package)
20+
21+
```bash
22+
yarn add @experimental-api-clients-automation/algoliasearch
23+
```
24+
25+
Or use a specific package to reduce bundle size:
26+
27+
```bash
28+
yarn add @experimental-api-clients-automation/client-search
29+
```
30+
31+
You can find the full list of available packages [here](https://www.npmjs.com/org/experimental-api-clients-automation).
32+
33+
### Without a package manager
34+
35+
Add the JavaScript to your `<head>`
36+
37+
```html
38+
<script src="https://cdn.jsdelivr.net/npm/@experimental-api-clients-automation/[email protected]/dist/algoliasearch.umd.browser.js"></script>
39+
```
40+
41+
## Using the client
42+
43+
Then you need to import the correct package, depending on your choice:
44+
45+
```js
46+
import { algoliasearch } from 'algoliasearch';
47+
48+
const client = algoliasearch(appId, apiKey);
49+
50+
// And access analytics or personalization client
51+
const analyticsClient = client.initAnalytics(analyticsAppId, analyticsApiKey);
52+
const personalizationCilent = client.initPersonalization(personalizationAppId, personalizationApiKey, 'eu');
53+
```
54+
55+
```js
56+
import { searchApi } from '@algolia/client-search';
57+
58+
const client = searchApi(appId, apiKey);
59+
```
60+
61+
It is possible to customize the client by passing optional parameters:
62+
63+
```js
64+
const client = searchApi(appId, apiKey, {
65+
requester: customRequester(),
66+
hosts: [{
67+
url: 'my.custom.host.net',
68+
accept: 'read',
69+
protocol: 'https',
70+
}]
71+
})
72+
```
73+
74+
Once the client is setup, you can enjoy all of Algolia API !
75+
76+
```js
77+
const res = await client.search({
78+
indexName: 'my-index',
79+
searchParams: { query: 'words to query' },
80+
});
81+
82+
console.log('Search result', res.hits);
83+
```
84+
85+
86+
Or with the `personalization` client
87+
88+
```js
89+
const res = await personalizationCilent.getUserTokenProfile({
90+
userToken: 'token',
91+
});
92+
93+
console.log('User scores', res.scores);
94+
```
95+
96+
</TabItem>
97+
</Tabs>

0 commit comments

Comments
 (0)