Convert manual from Wiki to mld

[MisterDA]

This allows to view the manual offline, and I think access it from the new docs website.

Converted with:

sed -E \
    -e 's/^==== *(.*) *====/{3 \1}/g' \
    -e 's/^=== *(.*) *===/{2 \1}/g' \
    -e 's/^== *(.*) *==/{1 \1}/g' \
    -e 's/^= *(.*) *=/{0 \1}/g' \
    -e 's/\[\[(.*)\|(.*)]]/{{: \1 }\2}/g' \
    -e 's|//(.*)//|{e \1}|g' \
    -e 's/<<a_api text=".*" *\| module (.+)>>/in {!\1}/g' \
    -e 's/<<code language="ocaml" *\|/{[\n/g' \
    -e 's/<<code language="c" *\|/{@c[/g' \
    -e 's/>>/]}/g' \
    -e "s/\`\`(.*)''/“\1”/g" \
    -e 's/\.\.\./…/g' \
    "$@" | \
    perl -pe 's|{{{(.*?)}}}|[\1]|g'

and then some manual fixes for lists and tables.

One shortcoming is that odoc doesn't have support for tables (see ocaml/odoc#864 and ocaml-doc/odoc-parser#11 for a concrete syntax proposal). There could be more references too, now they're just inline code blocks. I don't know how well it'll play with the existing Lwt website and wikidoc.

[raphael-proust]

For personal projects and such I always use md and so I'm quite happy about this PR. However, we need to still be able to push documentation to the official website. Currently, the way this happens is through the wikidoc branch where everything is supposed to be in .wiki format.

We can try to use md2mld and wikidoc (ocaml-doc to wiki) but it'll likely be brittle and fail to handle some useful cases like tables and such. The pandoc conversion tool might be a better solution although it adds a significant dependency to deploying the doc.

Do you have ideas?

[smorimoto]

There may be an option to wait until they are implemented. In fact, tables, nested lists, and so on are mandatory.

[MisterDA]

Note that this uses the mld syntax (odoc's syntax for documentation), not Markdown. I believe you can use odoc to have it generate the documentation instead of wikidoc or md2mld. It would perhaps use some external tweaking to fit in the website style.

I think it would be great to have the manual accessible offline and through odig/odoc.

btw the docs/Makefile seems outdated.

[raphael-proust]

Oh yes indeed! I got confused and just read md where it clearly says mld. My bad.

The makefile is indeed outdated. In fact, generating the documentation is quite complicated right now because of conflicting version constraints between wikidoc, domainslib, and ppx. I think a full rehaul of the documentation build might be needed. And we can probably switch the documentation format at the same time.

[raphael-proust]

The tables don't seem to render when I build the doc locally. Is the version of odoc that supports tables already released? I have 2.2.0 locally and opam says that's the latest released version.

[raphael-proust]

You should add the dependency to odoc in the opam file.

[MisterDA]

Tables will be part of odoc 2.3.0, currently in development and unreleased.

[raphael-proust]

Ok. I've added the odoc>=2.3.0 dependency in the opam file. Ping me when the new version is released.

[MisterDA]

odoc.2.3.0 has been released!

[raphael-proust]

I tried this locally and it all builds fine and displays well. I'm in favour of merging, which I'll do shortly unless someone raises some concerns.