dev meeting 20210127

Present at the meeting:

• James Somers (@jsomers)
• Etienne Millon (@emillon)
• Jon Ludlam (@jonludlam)
• Nathan Rebours (@NathanReb)

Meeting notes

Adding metadata to code blocks in mli files

As mdx gets more popular, one popular feature request is adding checked code examples in mli files. There is some support in mdx already, but this has some limitations. In particular, there's no odoc syntax to attach metadata to code blocks, for example to specify which language the example is written in (it's assumed to be ocaml), or to attach "tags" to them (mdx uses tags like this to skip certain blocks, pass environment variables, etc).

To support that, odoc syntax needs to be extended to support that. Ocamlformat might need to get adapted too.

There is actually a PR open about a very similar feature: Extract code blocks by ID. This dates from before mdx was stable and it seems that most of the features outlined in this PR would be better handled by mdx.

At the moment mld files are not supported by mdx but the corresponding parser is already in use in mdx so this would only be a matter of plugging the right bits together.

Regarding separating concerns, it seems better to just embed a string somewhere in the odoc AST and let mdx parse and interpret it (similarly to how it is embedded in a HTML comment).

For the language itself, it seems it should be detected rather than explicit (this is mostly a question of toplevel vs normal ocaml). Mdx can do this detection, but this is important for odoc too so that it can highlight the blocks. Today there is a dependency cycle between mdx and odoc but this cycle can be broken by extracting a small library for odoc's parser or mdx's parser.

The next step is to revive the PR and come up with a good concrete syntax, this is going to be brought up at the next odoc meeting.

Linking between odoc and mdx

Mdx and odoc both supports hyperlinks but they are each living in their own namespace.

It would be useful to cross the gap so that a mdx tutorial can link to the odoc documentation to the relevant functions; or that the reference documentation can link to a mdx tutorial.

With markdown files this would not directly be handled by odoc but rather by the driver that would build the documentation website. Some sort of odoc:// convention for links would be necessary to translate to the correct URLs.

Using mld files it might be a bit easier since the links can be expressed. There is a tool to convert from md to the mld format.