Build Belt/Js docs with ODoc #3379
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
| First result :) |
| Some more screenshots of the progress:
|
Todo:
|
| For the `Arity_2 stuff, here is what we did https://github.com/bucklescript/bucklescript/blob/master/vendor/ocaml/typing/oprint.ml#L194 |
| I can't seem to find a lot of time to work on this lately, so I'll open it up for Review in the meantime. Please consider the Todo list above! |
| Closing as stale. There are other relevant discussions elsewhere. |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
Opening for visibility 🗣
Purpose
To properly adopt odoc as the official documentation tool in BuckleScript, I figured it made sense to have its libraries built with it. This PR attempts to rebuild the documentation for the Belt and Js libraries.
This builds, indirectly, towards #3198 Automatic Documentation Generation.
Approach
odoc is included as a development time dependency of BuckleScript, and it's managed via esy. The reason to do this is to avoid versioning conflicts, as odoc must be compiled with the same compiler version used to compile the artifacts it will work on.
That is, if odoc is compiled with 4.06, it will not work with artifacts from a 4.02 compiler.
From there, odoc is invoked through esy in a special ninja flow:
jscomp/docs.ninja. This flow will take care of building all the.cmtifiles required, and turning them into.odocfiles. Ultimately, it will turn those into.htmlfiles ready for publishing.Conflicts
Belt and Js are built with
bsc, which uses a patched typed tree that breaks odoc's expectations of a standard 4.02.3.cmtifile. This means that we need to build odoc with the exact compiler version used bybsc. That is,4.02.3+BS, the compiler fork that lives here: https://github.com/BuckleScript/ocamlTo make use of that fork, we can extend it to be included as an esy dependency (rescript-lang/ocaml#24). I could use some help in getting this in a working state. Refer to that PR for more info.
Still working through it, let me know what you think!
cc/ @bobzhang @jordwalke @ryyppy @nikgraf