---
tags: minutes
---

# Odoc dev meeting 11/02/21

## Attendees

- @jonludlam
- @lubegasimon
- @lpw25
- @drup
- @lukemaurer
- @Octachron
- @Julow

## 2.0 Release

Outstanding issues:

### Documentation / Reference driver

New implementation - previous one 'blossomed' into the driver for docs.ocaml.org and got too complicated:

https://github.com/jonludlam/odoc/tree/reference-driver-v2

Driver implemented as an mdx file:
https://github.com/jonludlam/odoc/blob/reference-driver-v2/doc/driver.md

Current output:
https://www.cl.cam.ac.uk/~jjl25/odoc_reference_driver/html/odoc/

### Issues

Does anyone have issues they'd like to add to this list?

https://github.com/ocaml/odoc/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0.0

- [#585](https://github.com/ocaml/odoc/issues/585) (references aren't working right) - Unassigned - why did this not get caught in CI!?

- [#557](https://github.com/ocaml/odoc/issues/557) (Command to extract errors from odocl files) - Unassigned

- [#508](https://github.com/ocaml/odoc/issues/508) (overridden values of modules included in another module still get rendered) @lubegasimon working on it (https://github.com/ocaml/odoc/pull/580)

- [#560](https://github.com/ocaml/odoc/issues/560) (Dead links to hidden items appearing in documentation) - @lubegasimon working on it (https://github.com/ocaml/odoc/pull/583)

- [#541](https://github.com/ocaml/odoc/issues/541) (Alignment "styles" (Center, Left, Right) are not supported) - Unassigned

- [#478](https://github.com/ocaml/odoc/issues/478) (Top-level doc-comments of module types are discarded) - Unassigned

- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - addressed above

- [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad) - addressed above

- [#297](https://github.com/ocaml/odoc/issues/297) (!modules should splice in docs) - Unassigned

- [#586](https://github.com/ocaml/odoc/issues/586) (CSS regression) @lubegasimon to fix

- [#587](https://github.com/ocaml/odoc/issues/587) (include Subst failure) - @jonludlam to fix

- [#558](https://github.com/ocaml/odoc/issues/558) (Support canonical on module types, types, etc.)

- [#559](https://github.com/ocaml/odoc/issues/559) (Canonical does not work on compilation units)

- [#577](https://github.com/ocaml/odoc/issues/577) (Support `{!indexlist}`)

## docs.ocaml.org

[docs.ocaml.org design](https://hackmd.io/@ocaml/SyMb4H_xd)

## Syntax of mdx-enabled comment blocks

From the slack chat, reproduced here for posterity:

Suggested syntax for passing metadata to mdx:

{@ocaml env=f1 version>=4.06 [
let promoted = code
]}

and for other languages explicitly enumerate them

{@sh [
# rm -rf /
]}

and for a toplevel

{@ocaml version=4.10.0 [
# let x = 1 ;;
val x : 1
]}

## Syntax for refences

docs.ocaml.org needs some escaping for references to allow page names with hyphens or dots in

Current: `{!baz:foo-?1.bar-?2.?3}`
?1, ?2 ~= ocaml module ident | `''` .... `''`
bar,foo,baz ~= [a-zA-Z_-]+
There's `{!module-type-foo}`

suggestion:

{!page-"foo.bar".label-baz}

TODO: make an issue for this!