Code generated documentation

[w8ski]

Is it possible to generate docs based on special comments in the codebase like:

/*
 * @Todo function
 * @params
 * name: string
 * isActive: boolean
 * @description
 * explain your function here
 */
function Todo(name, isActive) {
 ...
}

I think this + MDX functionality (that already exists) would cover all the bases.

[dimaMachina]

currently not possible, but any ideas how this can be done are welcome

[pixelass]

I'm not fully sure what the exact question is here. I'll assume that the OP wants to generate documentation from docblocks. Here's how we handle this in 2 different cases:

Here's the website (see header links Core API and SDK): https://get-captain.com/

You can find the source code here: https://github.com/blib-la/captain
Look at our deployment workflow (currently using gh-pages): https://github.com/blib-la/captain/blob/alpha/.github/workflows/publish-homepage.yml

We have an app that consumes our sdk which is a separate monorepo. We wanted to display both API documentations so we did this:

1. We use multiple separate typedoc configs to generate markdown from our codebase

• Core API refers to the source code of the repo (see typedoc.*.json) Example: https://github.com/blib-la/captain/blob/alpha/typedoc.electron.json
• SDK is generated from the node_modules (see files prefixed with typedoc.captn-*) Example: https://github.com/blib-la/captain/blob/alpha/typedoc.captn-joy.json

2. Everything is generated into homepage/pages/* where we already provide some basic files.

• Generated files are ignored in our .gitignore: https://github.com/blib-la/captain/blob/d527d0ea434f6ea911b48f86fadac29a741c96ba/.gitignore#L28-L39

3. We have special folders in pages which serve as templates with _meta.json files. Since next.js ignores _* prefixed directories, this works like a charm. Example: https://github.com/blib-la/captain/tree/alpha/homepage/pages/_captain-sdk
4. Typedoc will clean directories so we run a script that copies the _meta.json files from our templates to the final output (e.g. pages/_captain-sdk/**/_meta.json to pages/captain-sdk/**/_meta.json), See: https://github.com/blib-la/captain/blob/alpha/scripts/nextra-meta.mjs

You can find the npm scripts in our package.json: https://github.com/blib-la/captain/blob/d527d0ea434f6ea911b48f86fadac29a741c96ba/package.json#L18-L31

I hope this is on topic and helps.

Note

Please respect, that our repository is published under AGPL 3.0, so unless you also publish AGPL 3.0, please DO NOT JUST COPY IT. You are obviously free to take inspiration, and if you need any help, we're always here to support ❤️