Docs: experiment with docsify

[jchavarri]

This is a small experiment for what could be the first version of docs (not counting existing example folder, which served its purpose, but I think can be retired now 😅 ).

This experiment is using docsify with some updates. I really liked docsify for a few reasons:

• It is very minimal and clean
• It is well integrated with markdown
• It support full text search out of the box
• And multi-lang, which could be useful
• Can be read from mobile
• No build step, just an html file (can be served with python -m SimpleHTTPServer, docsify-cli or any other server)

Some more things:

Embed .ml files

Through a tiny change in docsify, there is the possibility to embed ml files partially, only the part between comments with (* [demo] *) in them.

This allows to have the doc snippets compiled with dune (including ppx, etc) very easily, apply ocamlformat to them transparently too, and then use them in the docs directly, see docs/snippets/basic.ml and how it renders.

Embed html files from odoc

It is possible to embed html in docsify as well. This allows to produce some html with odoc, and then just copy the content to the docs folder to be shown with the rest of the docs, see example.

One question here is if we will be able to put all the docs at the top level component (React) because otherwise I don't think the embedding will work, as it'll be very hard to maintain (one has to reproduce the hierarchy of odoc manually in docsify). This is probably the part that makes me hesitate more.

Docs initial structure

I added as well some initial structure for the docs (more details about subsections in link below):

• Introduction
• Main concepts
• Guides
• API

The example to see how all the above works can be seen in https://ml-in-barcelona.github.io/jsoo-react/docs/.

Let me know what you think :) any feedback welcome, about structure, choice of libs, embedding etc.

[jchavarri]

Merging this to keep working on docs, will open new PRs with added pages.