js_of_ocaml
js_of_ocaml copied to clipboard
ocsigen
DRAFT: use docusaurus for a new documentation
Draft - Introduction
(sorry for the bad quality PR for the moment)
I would like to open the discussion about a brand new documentation for jsoo. It is not a secret that the documentation is not really pretty and easy to read. It is not also easy to maintain. It is also not easy to contribute to because it does imply to know how html_of_wiki does work and it is not well documented. The UI is quite the same.
Since some years, we see new documentation/blog generators. The Ocsigen project did move to Jekyll to write a blog for instance some years ago. It was a big step! Most of them are based on markdown and I think it became the norm.
I suggest to switch to something new, and I suggest docusaurus. It does support versioning as we would like, and it does also support blog and doc. It does also support dark mode out-of-the-box. Plugins can be added easily. It can also support multiple programming languages snippets (for OCaml/Reason).
The website can be generated moving to doc and running yarn build (npm install -g yarn if you don't have yarn).
It is only a WIP, mainly changing the wiki file to markdown.
The migration should not take that much. Modifying quickly the wiki files took me about 1h30. I haven't yet continued because I wanted to have your opinion first.
The crosslink projects could be also supported in addition to API (can be generated through odoc for instance, and added in the navbar). The migration can be done project by project. I would say one day and a half would be enough to get something nice.
The project can be automatically deployed in the CI.
Screenshots
@balat @hhugo opinions?
A naïve question but what is the gain over using plain Odoc?
You can still use odoc for the documentation of the code, and link it. Tutorials or use-cases/real world examples requires a separated documentation (often).
Tutorials or use-cases/real world examples requires a separated documentation (often).
You have .mld files for that which have the advantage of checked cross references into your API docs and easy local access (via odig) for end users when they install js_of_ocaml via opam.
I don't have a strict objection but we need to be sure that it is the right tool before deciding something. Do you have an idea about the tools other projects are using for generating their documentation?
My other concerns are about transition and uniformity. Who is going to do that? We want to avoid a patchwork of graphically unrelated pages, as it is the case for js_of_ocaml. How is it going to be included in the site? Can we keep all the features (translation to reason, customizable stylesheet for individual elements)?
Writing the documentation in .mld is a lot more future proof, given how odoc is moving along.
