Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Redo the documentation #299

Open
pbiggar opened this issue Oct 12, 2022 · 0 comments
Open

Redo the documentation #299

pbiggar opened this issue Oct 12, 2022 · 0 comments
Assignees
Labels
documentation f# Applies to the F# variant help wanted Extra attention is needed ocaml Applies to the OCaml version rescript Applies to the rescript version

Comments

@pbiggar
Copy link
Member

pbiggar commented Oct 12, 2022

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.

@pbiggar pbiggar added help wanted Extra attention is needed documentation rescript Applies to the rescript version f# Applies to the F# variant ocaml Applies to the OCaml version labels Oct 12, 2022
@pbiggar pbiggar added this to the 0.1.0 milestone Oct 12, 2022
@pbiggar pbiggar self-assigned this Oct 13, 2022
This was referenced Oct 13, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation f# Applies to the F# variant help wanted Extra attention is needed ocaml Applies to the OCaml version rescript Applies to the rescript version
Projects
None yet
Development

No branches or pull requests

1 participant