-
Notifications
You must be signed in to change notification settings - Fork 172
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
Convert manual from Wiki to mld #951
Conversation
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 We can try to use Do you have ideas? |
There may be an option to wait until they are implemented. In fact, tables, nested lists, and so on are mandatory. |
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 |
Oh yes indeed! I got confused and just read 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. |
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. |
You should add the dependency to |
Tables will be part of odoc 2.3.0, currently in development and unreleased. |
Ok. I've added the |
odoc.2.3.0 has been released! |
This allows to view the manual offline. 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.
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. |
This allows to view the manual offline, and I think access it from the new docs website.
Converted with:
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.