docs: generate doc from specs

[shortcuts]

🧭 What and Why

🎟 JIRA Ticket: https://algolia.atlassian.net/browse/APIC-260

Summary

This website is hosted on Netlify and built with Docusaurus.

We are using the Redocusaurus plugin to generate documentation for our bundled specs files

Deploys

You can have a preview of the website here: https://api-clients-automation.netlify.app/

Deploy will only happens when the website or specs/bundled/ folder have changed.

Feedbacks

• Error responses are not always correct in our specs: https://algolia.atlassian.net/browse/APIC-265
• We should be able to improve the output of the generated specs pages by swizzling the component

🧪 Test

• CI :D
• Preview: https://api-clients-automation.netlify.app/

[netlify]

✔️ Deploy Preview for api-clients-automation canceled.

🔨 Explore the source changes: 6f2b95e

🔍 Inspect the deploy log: https://app.netlify.com/sites/api-clients-automation/deploys/621f8f8fb4ed060008b4827c

[shortcuts]

Just asking for a review to gather thoughts on this

[millotp]

Light mode makes the page crash, good way to prevent users from burning their eyes

[shortcuts]

Light mode makes the page crash, good way to prevent users from burning their eyes

I guess this is why only dark mode is available on their demo 🤔

[shortcuts]

Unless we want to go with a full-dark-mode I don't think we will be able to use this plugin.

[shortcuts]

I've added the docs here https://github.com/algolia/api-clients-automation/tree/main/docs

[bodinsamuel]

this looks very good, few more comments:

• Can you update your PR desc to reflect actual PR content
• There is an issue when you scroll, the top navbar disappear leaving a blank zone
• Can we log an issue on our side to use tags more extensively so endpoints can be grouped, cf: https://petstore.swagger.io/v2/swagger.json and results https://rohit-gohri.github.io/redocusaurus/examples/using-spec-url/#tag/user
• Currently the doc is mixing internal doc for this repo and external doc, is there any way to better split the two?

[shortcuts]

Can you update your PR desc to reflect actual PR content

Done!

Can we log an issue on our side to use tags more extensively so endpoints can be grouped, cf:

Do you mostly refer to the search spec here? We've decided to try to split this one in smaller specs to avoid having everything under it

There is an issue when you scroll, the top navbar disappear leaving a blank zone

Good catch, I believe Redocusaurus does not support the hideOnScroll option

Currently the doc is mixing internal doc for this repo and external doc, is there any way to better split the two?

For now docs only hosts documentation for our repository, but we could have API client snippets under and other group yes

[bodinsamuel]

Do you mostly refer to the search spec here? We've decided to try to split this one in smaller specs to avoid having everything under it

Most API have implicit grouping that can not be split into sub-client.
For example QS has:
/logs
/configs

In the UI if you put tags, they can be split by Configs and Logs

[shortcuts]

Most API have implicit grouping that can not be split into sub-client.

Ah yes make sense, however since it's the same specs that we use for the generation it would have an impact on that to add more tags to it, we need to do a bit of testing here

[shortcuts]

Final review before merging anyone? Or an approval :D

[damcou]

🚀