We'll convert odoc HTML into GitHub Flavored
(gfm), then we'll format the Markdown, after which we'll lift Markdown code blocks
::code-block:: LANGUAGE into
fenced code blocks,
and then use MyST to
render the Markdown into HTML.
Odoc.html mli |> Pandoc.gfm |> Mdformat.format
|> lift_code_block |> MyST_docutils.html5
The proposal is to render Odoc verbatim blocks of the form
into syntax highlighted code blocks.
The design choices in the proposal are:
- Literate: Be understandable when the .mli file is read in a text editor
- Backwards-compatible: Not look like garbage if the feature is not available in an Odoc version
If the proposal is adopted, it may take quite a while before the proposal is implemented. In the meantime early adopters can use this experiment to adopt this feature into their own projects.
- see the rendering of the .mli file
Please file an issue (or +1 an existing issue) if you like/dislike the proposal, or have implementation ideas. Visit https://github.com/diskuv/odoc-sandbox/issues.