RFC: A stunning documentation

[eric-burel]

Since Next is supposed to be an efficient static build tool, I think it would be relevant to put the docs within the starter.

• [x] Install MDX in the starter. You can now edit src/pages/docs folder and get the documentation automatically generated when you run the app. It's available on http://localhost:3000/docs locally.
• [X] Automatically generate documentation based on TS typings? From @Apollinaire: the Apollo documentation is an example of how to generate the doc from TypeScript. They seem to combine Gatsby, Typedoc, and MDX to render the documentation while being able to automate many tasks and keep the API in sync.
• [ ] Host the TS documentation on Vercel instead of Netlify
• [ ] Docusaurus seems more apprioriate thant he Next.js embedded documentation: https://docusaurus.io/ We should keep the Next.js .mdx setup as a demo, but use Docusaurus for Vulcan documentation, both for NPM and Next.js versions
• [ ] Publish Vulcan NPM Storybook on either Chromatic or Vercel as a build site
• [ ] Write the best doc ever
• [X] Find patterns for interactive docs, eg Vulcan's getting started or Next dynamic quizz => this the /learn page
• [ ] Organize Q&A, write articles, do videos...

[eric-burel]

@Timi-Duban it would be awesome to manage to handle point 2 (automatically generate documentation based on TS typings) for Vulcan NPM. The end result would be a documentation that shows the typings of all exported values for each package, so you can tell what you can import from each package and get the API.

[Timi-Duban]

I found a module that handles this, it's called TypeDoc. It's based on TS typing and provides a doc about everything that's exported (like classes, interfaces, types aliases, variables, functions...)

It seems to throw if typecheck throws, which can be a problem. For example I have a weird bug in packages/react-ui/components/form/tests/FormContainer.stories.tsx where typescript doesn't want to export buildUpdateQuery so I deleted it to test the documentation tool.

I don't think it's the perfect solution: it kinda feels like you're navigating in our types. But since it can be accessed more easily it can be usefull. It looks like this:

Another problem: to have a pretty result, you have to give the command every index.ts file (or it will consider every folder as a module and you'll end up with repetitions). For example in vulcan-npm what seems the best way to use it to me is:

yarn add typedoc --dev -W
npx typedoc packages/core/index.ts packages/demo/index.ts packages/graphql/index.ts packages/i18n/index.ts  packages/mdx/index.ts packages/meteor-legacy/index.ts packages/model/index.ts packages/mongo/index.ts packages/multi-env-demo/index.ts packages/permissions/index.ts packages/react-hooks/index.ts packages/react-ui/index.ts packages/schema/index.ts packages/utils/index.ts

The result is either HTML or JSON files, by default it's HTML located to /docs (but you can change it by doing npx typedoc --out [your new location] [files] You can also add the flag --excludeNotDocumented, but we don't have much of our functions commented so we lose a lot by doing this.

They have Monorepos handling, but it seems to crash in vulcan-npm. I'll try in vulcan-next and keep you informed.

[eric-burel]

That's not bad already even if it has limitations. Thanks! Vulcan NPM is the priority here, for Vulcan Next you can focus on the local packages in the packages folder.

[Timi-Duban]

It's exactly the same in vulcan-next, but there are very few packages that are interesting (Apollo and Utils could be for example). So for now the priority is to pass vulcan-npm typecheck to be able to automatically generate documentation !