From 8aa4649bda38f741302117872e8525228a2e573a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Vannicatte?= Date: Wed, 25 May 2022 11:42:51 +0200 Subject: [PATCH] docs: make endpoints naming consistent (#543) --- README.md | 12 +++---- website/docs/automation/introduction.md | 32 ------------------- .../guides/filtering-your-search.mdx | 0 .../guides/retrieving-facets.mdx | 0 .../guides/send-data-to-algolia.mdx | 19 ++++++----- .../{api-clients => clients}/installation.mdx | 0 .../{api-clients => clients}/introduction.md | 6 ++-- .../migration-guide.mdx | 4 +-- .../CLI/clients-commands.md | 0 .../CLI/cts-commands.md | 0 .../CLI/specs-commands.md | 0 .../add-new-api-client.md | 8 ++--- .../add-new-language.md | 13 ++++---- .../commit-and-pull-request.md | 0 website/docs/contributing/introduction.md | 32 +++++++++++++++++++ .../release-process.md | 0 .../setup-repository.md | 10 +++--- .../testing/common-test-suite.md | 2 +- .../testing/playground.md | 2 +- website/docusaurus.config.js | 4 +-- website/sidebars.js | 32 +++++++++---------- 21 files changed, 88 insertions(+), 88 deletions(-) delete mode 100644 website/docs/automation/introduction.md rename website/docs/{api-clients => clients}/guides/filtering-your-search.mdx (100%) rename website/docs/{api-clients => clients}/guides/retrieving-facets.mdx (100%) rename website/docs/{api-clients => clients}/guides/send-data-to-algolia.mdx (90%) rename website/docs/{api-clients => clients}/installation.mdx (100%) rename website/docs/{api-clients => clients}/introduction.md (77%) rename website/docs/{api-clients => clients}/migration-guide.mdx (96%) rename website/docs/{automation => contributing}/CLI/clients-commands.md (100%) rename website/docs/{automation => contributing}/CLI/cts-commands.md (100%) rename website/docs/{automation => contributing}/CLI/specs-commands.md (100%) rename website/docs/{automation => contributing}/add-new-api-client.md (92%) rename website/docs/{automation => contributing}/add-new-language.md (92%) rename website/docs/{automation => contributing}/commit-and-pull-request.md (100%) create mode 100644 website/docs/contributing/introduction.md rename website/docs/{automation => contributing}/release-process.md (100%) rename website/docs/{automation => contributing}/setup-repository.md (79%) rename website/docs/{automation => contributing}/testing/common-test-suite.md (98%) rename website/docs/{automation => contributing}/testing/playground.md (90%) diff --git a/README.md b/README.md index 12ac269fbd..471c47a8eb 100644 --- a/README.md +++ b/README.md @@ -14,13 +14,13 @@ nvm use && yarn yarn docker:setup ``` -[Read more on our documentation](https://api-clients-automation.netlify.app/docs/automation/setup-repository) +[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/setup-repository) ## Contributing You can make changes locally and run commands through the docker container. -[Specs CLI commands](https://api-clients-automation.netlify.app/docs/automation/CLI/specs-commands) • [Clients CLI commands](https://api-clients-automation.netlify.app/docs/automation/CLI/clients-commands) • [CTS CLI commands](https://api-clients-automation.netlify.app/docs/automation/CLI/cts-commands) +[Specs CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/specs-commands) • [Clients CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/clients-commands) • [CTS CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/cts-commands) ### Build and validate specs @@ -30,7 +30,7 @@ You can make changes locally and run commands through the docker container. yarn docker build specs ``` -[Read more on our documentation](https://api-clients-automation.netlify.app/docs/automation/add-new-api-client) +[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/add-new-api-client) ### Generate clients based on the [`specs`](./specs/) @@ -40,11 +40,11 @@ yarn docker build specs yarn docker generate ``` -[Read more on our documentation](https://api-clients-automation.netlify.app/docs/automation/add-new-language) +[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/add-new-language) ## Testing clients You can test our generated clients by running: -- The playground [`playground`](./playground) ([Playground](https://api-clients-automation.netlify.app/docs/automation/testing/playground.md)) -- Tests with our [`Common Test Suite`](./tests/) ([Common Test Suite](https://api-clients-automation.netlify.app/docs/automation/testing/common-test-suite.md)). +- The playground [`playground`](./playground) ([Playground](https://api-clients-automation.netlify.app/docs/contributing/testing/playground.md)) +- Tests with our [`Common Test Suite`](./tests/) ([Common Test Suite](https://api-clients-automation.netlify.app/docs/contributing/testing/common-test-suite.md)). diff --git a/website/docs/automation/introduction.md b/website/docs/automation/introduction.md deleted file mode 100644 index 57efcf3d95..0000000000 --- a/website/docs/automation/introduction.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Introduction ---- - -# Introduction - -This section hosts informations about the [API clients automation](https://github.com/algolia/api-clients-automation) repository. For informations regarding the clients usage, see [the clients page](/docs/api-clients/introduction). - -## Contributing - -To contribute to the repository, make sure to take a look at our guidelines and recommendations: - -- [Setup the repository tooling](/docs/automation/setup-repository): to install our tooling. - - CLI commands can be found at [CLI > specs commands](/docs/automation/CLI/specs-commands), [CLI > clients commands](/docs/automation/CLI/clients-commands) and [CLI > CTS commands](/docs/automation/CLI/cts-commands). -- [Add a new client](/docs/automation/add-new-api-client): to add a new API spec to generate a client. -- [Support a new language](/docs/automation/add-new-language): to add a new supported language to the API clients. -- [Commit and Pull-request](/docs/automation/commit-and-pull-request): to see what to commit and send pull-requests. -- [Release process](/docs/automation/release-process): to see how to release API clients. - -## Testing - -Generated clients can be tested via the: - -- [Common Test Suite](/docs/automation/testing/common-test-suite) -- [Playground](/docs/automation/testing/playground) - -## Feedbacks - -To report feedbacks, please use: - -- [GitHub issues](https://github.com/algolia/api-clients-automation/issues) -- [#api-clients-beta-testers slack channel](https://algolia.slack.com/archives/C0341QDM3EG) diff --git a/website/docs/api-clients/guides/filtering-your-search.mdx b/website/docs/clients/guides/filtering-your-search.mdx similarity index 100% rename from website/docs/api-clients/guides/filtering-your-search.mdx rename to website/docs/clients/guides/filtering-your-search.mdx diff --git a/website/docs/api-clients/guides/retrieving-facets.mdx b/website/docs/clients/guides/retrieving-facets.mdx similarity index 100% rename from website/docs/api-clients/guides/retrieving-facets.mdx rename to website/docs/clients/guides/retrieving-facets.mdx diff --git a/website/docs/api-clients/guides/send-data-to-algolia.mdx b/website/docs/clients/guides/send-data-to-algolia.mdx similarity index 90% rename from website/docs/api-clients/guides/send-data-to-algolia.mdx rename to website/docs/clients/guides/send-data-to-algolia.mdx index 8901912964..a4eaec2def 100644 --- a/website/docs/api-clients/guides/send-data-to-algolia.mdx +++ b/website/docs/clients/guides/send-data-to-algolia.mdx @@ -15,7 +15,7 @@ To push data to Algolia, you need an Application ID and a valid API key with the ## Setting up the API client -> [Make sure to also read the Installation page](/docs/api-clients/installation). +> [Make sure to also read the Installation page](/docs/clients/installation). ', ''); - ```php - ', - '' - ); - ``` +```php +', + '' +); +``` + @@ -74,7 +75,6 @@ for (const record of records) { body: record, }); } - ``` @@ -92,7 +92,6 @@ foreach ($records as $record) { $record ); } - ``` diff --git a/website/docs/api-clients/installation.mdx b/website/docs/clients/installation.mdx similarity index 100% rename from website/docs/api-clients/installation.mdx rename to website/docs/clients/installation.mdx diff --git a/website/docs/api-clients/introduction.md b/website/docs/clients/introduction.md similarity index 77% rename from website/docs/api-clients/introduction.md rename to website/docs/clients/introduction.md index 1dd69c05f1..e174fff177 100644 --- a/website/docs/api-clients/introduction.md +++ b/website/docs/clients/introduction.md @@ -4,7 +4,7 @@ title: Introduction # Introduction -This section hosts informations about the [usage of the API clients](https://github.com/algolia/api-clients-automation). For informations regarding the automation and how to contribute, see [the automation page](/docs/automation/introduction). +This section hosts informations about the [usage of the API clients](https://github.com/algolia/api-clients-automation). For informations regarding the automation and how to contribute, see [the automation page](/docs/contributing/introduction). ## Repositories @@ -16,9 +16,9 @@ Generated code in production can be find on repository of the clients. ## Usage -See [the installation](/docs/api-clients/installation) page. +See [the installation](/docs/clients/installation) page. -You can also check the [playground](/docs/automation/testing/playground) if you'd like to test clients locally. +You can also check the [playground](/docs/contributing/testing/playground) if you'd like to test clients locally. ## Feedbacks diff --git a/website/docs/api-clients/migration-guide.mdx b/website/docs/clients/migration-guide.mdx similarity index 96% rename from website/docs/api-clients/migration-guide.mdx rename to website/docs/clients/migration-guide.mdx index 0ce0e7ac89..b79b1b0032 100644 --- a/website/docs/api-clients/migration-guide.mdx +++ b/website/docs/clients/migration-guide.mdx @@ -27,7 +27,7 @@ The changes below are effective on all of the API clients. The changes below are effective on the selected API client. -For informations regarding the installation of the package, please see [the installation page](/docs/api-clients/installation) +For informations regarding the installation of the package, please see [the installation page](/docs/clients/installation) You can find all the commands in the [CLI > clients commands page](/docs/automation/CLI/clients-commands) and [CLI > specs commands page](/docs/automation/CLI/specs-commands). +> You can find all the commands in the [CLI > clients commands page](/docs/contributing/CLI/clients-commands) and [CLI > specs commands page](/docs/contributing/CLI/specs-commands). ```bash yarn docker generate @@ -96,4 +96,4 @@ yarn docker generate ## 4. Implementing the Common Test Suite -Clients needs to be tested, you can read more in the [Common Test Suite](/docs/automation/testing/common-test-suite) guide. +Clients needs to be tested, you can read more in the [Common Test Suite](/docs/contributing/testing/common-test-suite) guide. diff --git a/website/docs/automation/add-new-language.md b/website/docs/contributing/add-new-language.md similarity index 92% rename from website/docs/automation/add-new-language.md rename to website/docs/contributing/add-new-language.md index b6aeb9f385..d636036fdd 100644 --- a/website/docs/automation/add-new-language.md +++ b/website/docs/contributing/add-new-language.md @@ -6,7 +6,7 @@ title: Support a new language :::info -Make sure to first [setup the repository tooling](/docs/automation/setup-repository) to ease your journey! +Make sure to first [setup the repository tooling](/docs/contributing/setup-repository) to ease your journey! You will also need to have the [openapi-generator](https://openapi-generator.tech/docs/installation/) installed. @@ -36,7 +36,7 @@ openapi-generator author template -g typescript-node -o templates/javascript/ Add each client in the file [`config/openapitools.json`](https://github.com/algolia/api-clients-automation/blob/main/config/openapitools.json), following the others client structure. -> See [`add a new client`](/docs/automation/add-new-api-client) for informations on how to structure your new client. +> See [`add a new client`](/docs/contributing/add-new-api-client) for informations on how to structure your new client. ### Algolia requirements @@ -77,7 +77,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 **yet**, 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/automation/add-new-api-client#generators). +As the generator does not support reading `servers` in a spec file **yet**, 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/contributing/add-new-api-client#generators). ### User Agent @@ -114,9 +114,10 @@ The function must be named `addAlgoliaAgent` because of JavaScript exception tha ### Dependencies You can use any dependency you want to create the client, it can be Json parser or HTTP client, but it's important to never expose those dependencies through the client, meaning: - - a function cannot return an object from a dependency - - a function cannot accept an object from a dependency as a parameter - - and so on + +- a function cannot return an object from a dependency +- a function cannot accept an object from a dependency as a parameter +- and so on It matters because when a dependency is exposed, a breaking change from our deps can affect the user code while the API client is still working correctly (because they have to use the dependency in their code), and that prevent us from upgrading our deps. In some languages it also requires the user to add our internal dependencies to his build system, which is very inconvenient and our clients should always be standalone. diff --git a/website/docs/automation/commit-and-pull-request.md b/website/docs/contributing/commit-and-pull-request.md similarity index 100% rename from website/docs/automation/commit-and-pull-request.md rename to website/docs/contributing/commit-and-pull-request.md diff --git a/website/docs/contributing/introduction.md b/website/docs/contributing/introduction.md new file mode 100644 index 0000000000..c38e521a0f --- /dev/null +++ b/website/docs/contributing/introduction.md @@ -0,0 +1,32 @@ +--- +title: Introduction +--- + +# Introduction + +This section hosts informations about the [API clients automation](https://github.com/algolia/api-clients-automation) repository. For informations regarding the clients usage, see [the clients page](/docs/clients/introduction). + +## Contributing + +To contribute to the repository, make sure to take a look at our guidelines and recommendations: + +- [Setup the repository tooling](/docs/contributing/setup-repository): to install our tooling. + - CLI commands can be found at [CLI > specs commands](/docs/contributing/CLI/specs-commands), [CLI > clients commands](/docs/contributing/CLI/clients-commands) and [CLI > CTS commands](/docs/contributing/CLI/cts-commands). +- [Add a new client](/docs/contributing/add-new-api-client): to add a new API spec to generate a client. +- [Support a new language](/docs/contributing/add-new-language): to add a new supported language to the API clients. +- [Commit and Pull-request](/docs/contributing/commit-and-pull-request): to see what to commit and send pull-requests. +- [Release process](/docs/contributing/release-process): to see how to release API clients. + +## Testing + +Generated clients can be tested via the: + +- [Common Test Suite](/docs/contributing/testing/common-test-suite) +- [Playground](/docs/contributing/testing/playground) + +## Feedbacks + +To report feedbacks, please use: + +- [GitHub issues](https://github.com/algolia/api-clients-automation/issues) +- [#api-clients-beta-testers slack channel](https://algolia.slack.com/archives/C0341QDM3EG) diff --git a/website/docs/automation/release-process.md b/website/docs/contributing/release-process.md similarity index 100% rename from website/docs/automation/release-process.md rename to website/docs/contributing/release-process.md diff --git a/website/docs/automation/setup-repository.md b/website/docs/contributing/setup-repository.md similarity index 79% rename from website/docs/automation/setup-repository.md rename to website/docs/contributing/setup-repository.md index d63b4b8ed0..57e3915c54 100644 --- a/website/docs/automation/setup-repository.md +++ b/website/docs/contributing/setup-repository.md @@ -54,11 +54,11 @@ yarn docker:clean Once you've successfully built and mounted the Docker image, you can now play with the repository! Read our guides on: -- [How to add a new client](/docs/automation/add-new-api-client) -- [How to add a new language](/docs/automation/add-new-language) -- [Use CLI specs commands](/docs/automation/CLI/specs-commands) -- [Use CLI clients commands](/docs/automation/CLI/clients-commands) -- [Use CLI Common Test Suite commands](/docs/automation/CLI/specs-commands) +- [How to add a new client](/docs/contributing/add-new-api-client) +- [How to add a new language](/docs/contributing/add-new-language) +- [Use CLI specs commands](/docs/contributing/CLI/specs-commands) +- [Use CLI clients commands](/docs/contributing/CLI/clients-commands) +- [Use CLI Common Test Suite commands](/docs/contributing/CLI/specs-commands) ## Troubleshooting diff --git a/website/docs/automation/testing/common-test-suite.md b/website/docs/contributing/testing/common-test-suite.md similarity index 98% rename from website/docs/automation/testing/common-test-suite.md rename to website/docs/contributing/testing/common-test-suite.md index e5591434b0..8f95e0a816 100644 --- a/website/docs/automation/testing/common-test-suite.md +++ b/website/docs/contributing/testing/common-test-suite.md @@ -11,7 +11,7 @@ It is automaticaly generated for all languages, from a JSON entry point. Common Test Suite requires all clients to be built. -[CLI commands for the Common Test Suite](/docs/automation/CLI/cts-commands) +[CLI commands for the Common Test Suite](/docs/contributing/CLI/cts-commands) ::: diff --git a/website/docs/automation/testing/playground.md b/website/docs/contributing/testing/playground.md similarity index 90% rename from website/docs/automation/testing/playground.md rename to website/docs/contributing/testing/playground.md index e002c9a14e..0e92b7f612 100644 --- a/website/docs/automation/testing/playground.md +++ b/website/docs/contributing/testing/playground.md @@ -8,7 +8,7 @@ All of the existing clients should have an active playground for you to test gen :::info -Make sure to first [setup the repository tooling](/docs/automation/setup-repository) to ease your journey! +Make sure to first [setup the repository tooling](/docs/contributing/setup-repository) to ease your journey! ::: diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index fd582f46ec..88ca5a937e 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -116,12 +116,12 @@ function getSpecsForNavBar() { // left { label: 'Clients', - to: 'docs/api-clients/introduction', + to: 'docs/clients/introduction', position: 'left', }, { label: 'Contributing', - to: 'docs/automation/introduction', + to: 'docs/contributing/introduction', position: 'right', }, { diff --git a/website/sidebars.js b/website/sidebars.js index fbbaad0058..3155764d1f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -4,21 +4,21 @@ const sidebars = { // Everything related to the API Clients Automation automation: [ - 'automation/introduction', + 'contributing/introduction', { type: 'category', label: 'Getting Started', collapsed: false, items: [ - 'automation/setup-repository', + 'contributing/setup-repository', { type: 'category', label: 'CLI', collapsed: false, items: [ - 'automation/CLI/specs-commands', - 'automation/CLI/clients-commands', - 'automation/CLI/cts-commands', + 'contributing/CLI/specs-commands', + 'contributing/CLI/clients-commands', + 'contributing/CLI/cts-commands', ], }, ], @@ -28,39 +28,39 @@ const sidebars = { label: 'Contributing', collapsed: false, items: [ - 'automation/add-new-api-client', - 'automation/add-new-language', + 'contributing/add-new-api-client', + 'contributing/add-new-language', { type: 'category', label: 'Testing', collapsed: false, items: [ - 'automation/testing/common-test-suite', - 'automation/testing/playground', + 'contributing/testing/common-test-suite', + 'contributing/testing/playground', ], }, - 'automation/commit-and-pull-request', - 'automation/release-process', + 'contributing/commit-and-pull-request', + 'contributing/release-process', ], }, ], // Everything related to the generated clients usage clients: [ - 'api-clients/introduction', + 'clients/introduction', { type: 'category', label: 'Getting Started', collapsed: false, - items: ['api-clients/installation', 'api-clients/migration-guide'], + items: ['clients/installation', 'clients/migration-guide'], }, { type: 'category', label: 'Guides', collapsed: false, items: [ - 'api-clients/guides/send-data-to-algolia', - 'api-clients/guides/filtering-your-search', - 'api-clients/guides/retrieving-facets', + 'clients/guides/send-data-to-algolia', + 'clients/guides/filtering-your-search', + 'clients/guides/retrieving-facets', ], }, ],