add auto-generated helpers reference

[ianstormtaylor]

Do you want to request a feature or report a bug?

Improvement.

What's the expected behavior?

Since we're already using the docblock comments to power IntelliSense documentation for VS Code (or anything else that supports it), it would be nice to have the API reference automatically generated from these comments.

I experimented with typedoc a while ago, but the project is not well maintained, so newer TypeScript features often break the output. And the output itself isn't designed well enough to be understandable except for very basic exports. So it won't really work for us.

Instead, I think the best approach is to use some tool (hopefully one exists?) to parse the source and get a TypeScript AST. And then turn that into strings of Markdown that GitBook can understand.

There may be an existing TS-to-Markdown tool out there, but I'm skeptical that it will have been designed well enough to actually get usable results.

So we'll likely need to have a small internal tool for ourself. I think the ideal would be to be able to point it at a single .ts file and generate a single .md file from that. Anything that tries to smartly infer the structure of the docs from the structure of source seems like it will be doomed.

If anyone can help with this it would be greatly appreciated!

The only constraint is that whatever we use must result in both (a) useful and understandable output, and (b) not be more than a handful dependencies and files to maintain.

Ideally we'd have references for:

• Helpers (eg. Node, Text, Path, Range, etc.)
• Transforms (eg. setNodes, insertFragment, etc.)
• Commands (eg. insert_text, delete_backward, etc.)
• Operations (eg. insert_text, set_node, etc.)

The differences in how each of those things is written in source is what seems to warrant a more custom approach.

---

cc @CameronAckermanSEL who was investigating earlier.

[horacioh]

for what is worth, here's a branch I pushed on my fork showing the result of running typedoc on the slate package: https://github.com/horacioh/slate/tree/reference-docs

the command I use to generate the markdown files was this one:

npx typedoc --plugin typedoc-plugin-markdown --out docs/reference packages/slate --ignoreCompilerErrors --hideSources --hideBreadcrumbs

hope this can help?

[Mangatt]

Are there any new developments regarding helpers docs? It's almost a year later and it's quite difficult to get idea how things works just from reading source code.

Don't get me wrong, Slate is amazing piece of code, but it would be much more accessible with proper docs.