#3156: Restructured docs

[vikram-dagger]

Relates to #3156

This PR includes auto-generated API documentation as requested in #3048. See that PR for more information on the plugin and approach used.

Some notes:

• Existing guides have been recategorized and in some cases split into separate documents.
• Extension pages are manually added here. These would be auto-generated as well in the future.
• Extension categorization is TBD. This PR proposes a first approach.
• The index page might benefit from a different layout.

[netlify]

❌ Deploy Preview for cloak-docs failed.

Name	Link
🔨 Latest commit	58fcc4c
🔍 Latest deploy log	https://app.netlify.com/sites/cloak-docs/deploys/6342d1960788d000099eeeb8

[samalba]

@vikram-dagger I tried to unblock the netlify preview URL but it fails. The command that netlify runs is: yarn build from the website directory. Not that it works with a simple yarn start. I tried locally the yarn build command and I get the same error that the netlify running:

✔ Server
  Compiled successfully in 14.14s

[WARNING] Docs markdown link couldn't be resolved: (../guides/bnzm7-writing_extensions.md) in "/Users/shad/forks/dagger/docs/concepts/hbf3z-extensions.md" for version current
[WARNING] Docs markdown link couldn't be resolved: (f5cij-extension_runtime_protocol.md) in "/Users/shad/forks/dagger/docs/guides/bnzm7-extensions.md" for version current
[WARNING] Docs markdown link couldn't be resolved: (f5cij-extension_runtime_protocol.md) in "/Users/shad/forks/dagger/docs/guides/bnzm7-extensions.md" for version current
[WARNING] Docs markdown link couldn't be resolved: (../guides/bnzm7-writing_extensions.md) in "/Users/shad/forks/dagger/docs/concepts/hbf3z-extensions.md" for version current
[WARNING] Docs markdown link couldn't be resolved: (f5cij-extension_runtime_protocol.md) in "/Users/shad/forks/dagger/docs/guides/bnzm7-extensions.md" for version current
[WARNING] Docs markdown link couldn't be resolved: (f5cij-extension_runtime_protocol.md) in "/Users/shad/forks/dagger/docs/guides/bnzm7-extensions.md" for version current

✔ Client
  

● Server █████████████████████████ cache (99%) shutdown IdleFileCachePlugin
 stored

[ERROR] Unable to build website for locale en.
[ERROR] Error: Docusaurus found broken links!

Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken links found:

- On source page path = /bnzm7/api-extensions:
   -> linking to f5cij-extension_runtime_protocol.md (resolved as: /bnzm7/f5cij-extension_runtime_protocol.md)

- On source page path = /hbf3z/extensions:
   -> linking to ../guides/bnzm7-writing_extensions.md (resolved as: /guides/bnzm7-writing_extensions.md)

    at throwError (/Users/shad/forks/dagger/website/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at handleBrokenLinks (/Users/shad/forks/dagger/website/node_modules/@docusaurus/core/lib/server/brokenLinks.js:153:47)
    at async buildLocale (/Users/shad/forks/dagger/website/node_modules/@docusaurus/core/lib/commands/build.js:177:5)
    at async tryToBuildLocale (/Users/shad/forks/dagger/website/node_modules/@docusaurus/core/lib/commands/build.js:38:20)
    at async mapAsyncSequential (/Users/shad/forks/dagger/website/node_modules/@docusaurus/utils/lib/jsUtils.js:34:24)
    at async Command.build (/Users/shad/forks/dagger/website/node_modules/@docusaurus/core/lib/commands/build.js:73:21)
[INFO] Docusaurus version: 2.0.1
Node version: v18.8.0
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

[samalba]

Until we find a way to fix the netlify preview, it's still reviewable locally:

cd ./website
yarn install
yarn start

@jpadams @shykes

[vikram-dagger]

Fixed broken links

[samalba]

Looks good to me, it follows what what discussed previously. It's a solid foundation 👍

@shykes you should take a look

[shykes]

@vikram-dagger I notice you reused a lot of the same content and moved it into the new structure. Do you still want a review of the content itself, or only of the structure for now?

[vikram-dagger]

@vikram-dagger I notice you reused a lot of the same content and moved it into the new structure. Do you still want a review of the content itself, or only of the structure for now?

The prior content has been restructured and split between Guides, Concepts and Tutorials sections. I assume these were reviewed when initially committed, so they don't need to be reviewed again. I suspect some of this will be outdated once the API stabilizes/may already be outdated and will need a rewrite later anyway.

I would like review of:

• the structure
• the new content, which is mainly the auto-generated API docs and sample extension pages

[mircubed]

@vikram-dagger I noticed a resource section on the intro page, but not a resource section on the sidebar? Also, I don't think the resource section matches what you were proposing earlier like links to events, social, etc?

I have a few talks that I would like to link somewhere within your docs structure, so we can point people to those recordings.

[vikram-dagger]

@vikram-dagger I noticed a resource section on the intro page, but not a resource section on the sidebar? Also, I don't think the resource section matches what you were proposing earlier like links to events, social, etc?

I have a few talks that I would like to link somewhere within your docs structure, so we can point people to those recordings.

Thanks for this callout. I didn't include that section deliberately as I didn't have any content/assets for it. As you have mentioned you have this content, I'll add it in my next update in this PR.

[mircubed]

Thanks! I created #951, so let me know if that is enough content for the page. I am happy to keep that page updated once it is created.

[samalba]

In case the preview URL is lost again, here it is: https://deploy-preview-3160--cloak-docs.netlify.app/

[vikram-dagger]

Closing this in favour of a simpler structure to start with, see #3360