docs: automatically generate api docs from source

[ST-DDT]

Automatically generates the api documentation using typedocs.

Based on PR #207 by @ericjeker

• Update Sidenav (manually)
• Add script to generate docs
• Generate docs (automatically)
• Verify that the generated pages looks good
• Remove the old api docs and generate them only during ci builds

[JessicaSachs]

Pulled it down and tried it. I love this. I think we could make the parameters a little prettier, but this is so much better than what exists, I think we should merge it now.

I feel a little awkward about committing generated source code... I think we should probably have CI re-build and publish the docs instead of committing them.

BUT! Regardless, I believe it is a good first step ❤️

[ericjeker]

I feel a little awkward about committing generated source code... I think we should probably have CI re-build and publish the docs instead of committing them.

Yes, same. I think we shouldn't commit that, otherwise the CI will create changes in the repo files, which is not good.

[ericjeker]

This looks great!

Can we have the sidenav automatically generated when looping on the modules maybe? IIRC we can use Frontmatter for that? Or simply generate a Javascript array that is then processed in the .vitepress/config?

[ST-DDT]

Can we have the sidenav automatically generated when looping on the modules maybe?

I will do that.

I think we should probably have CI re-build and publish the docs instead of committing them.

My original idea was to attach it to a pre commit hook, but on the fly generation is probably best.

I think we could make the parameters a little prettier

Any suggestion how it should look like?
E.g. a table?

[prisis]

I would only generate the code in the ci if the docs are build, so there is always up to date version live and put the docs/api to gitignore

[Shinigami92]

I would only generate the code in the ci if the docs are build, so there is always up to date version live and put the docs/api to gitignore

Also we have to do it like that, otherwise it could be hard to setup a CI that especially bypasses admin privileges to push into main branch

[JessicaSachs]

Yeah, build it on CI and .gitignore the local files.

@ST-DDT I was looking for inspo when I did this PR review earlier... I think Styleguidist has a decent UI

https://react-kawaii.vercel.app/#/Components?id=cat

[Shinigami92]

What are your thoughts about localization support for that? #196

[ST-DDT]

@JessicaSachs Like this?

I changed the command to manually generate the files to pnpm run docs:api,
but they are also generated during pnpm run build.

[Shinigami92]

I will approve that now, but we should document

• which script should be run by humans in which order
• which scripts are required by CI/netlify-toml
• which are "just" sub-scripts
  Could you open an issue for that, to track it? (or maybe it's part of Documentate teams, labels, boards ... #308)