Currently, the documentation is generated by parsing code and generated files and converting it into model.json, which is then used to generate website code. This means that the .mli files are the source of truth, and it has the advantage of using the exact generated output.
There are some disadvantages to this approach though:
- not sure if it will work for rescript
- complicated setup involving ocaml toolchain
- won't work for F#
- is designed for functions which are the same but have different syntaxes, not different functions.
I propose we take the opposite approach:
- have human edited files (perhaps yaml) with the docstrings and function names
- generate .fsi/.resi/.mli files from those
- generate separate pages in the website for each language
Other goals:
- support for different versions (like docusaurus allows)
Alternatively, instead of generating our own code, we could use output from each language's own documentation toolchain (rescript currently uses odoc as well though), and either link to it from the website or embed it somehow.
Currently, the documentation is generated by parsing code and generated files and converting it into model.json, which is then used to generate website code. This means that the .mli files are the source of truth, and it has the advantage of using the exact generated output.
There are some disadvantages to this approach though:
I propose we take the opposite approach:
Other goals:
Alternatively, instead of generating our own code, we could use output from each language's own documentation toolchain (rescript currently uses odoc as well though), and either link to it from the website or embed it somehow.