Skip to content

Dev meeting 2021 04 08

Jump to bottom
Jon Ludlam edited this page May 6, 2021 · 1 revision

tags: minutes

Odoc dev meeting 2021-04-08

Attendees

@jonludlam @lpw25 @lubega-simon @julow @avsm @drup

2.0 issues

For discussion:

  • #658 - Don't resolve references in synopses in {!modules} lists

The synopsis of a module would normally be resolved in the context of that module. However, it may be pulled out and inserted at any other place via a {!modules} expression. The consequence of this is that any reference within it will be very difficult to resolve, since we wont have the environment of the module.

This PR will not try to resolve the reference but instead emit a warning.

Any other suggestions?

  • @lpw25 : raise a warning if it doesn't resolve - try to resolve it in the global scope.

New:

  • #659 (Resolution bug for sections)

  • #656 (Aliases aren't created in includes when strengthening modules) - PR open: #653

Fixed since last time:

  • #645 (Comment attached to include are dropped)

In progress:

  • #650 (Need ModuleType 'aliases') - @jonludlam

  • #648 (Warnings about ambigous references are bogus) - @jonludlam

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon

  • #460 (reference driver needed) - in progress, on hold - @jonludlam

  • #573 (docs are bad) - in progress, on hold - @jonludlam

  • #557 (Command to extract errors from odocl files) - @jonludlam

  • #632 (No synopsis rendered for modules) - partial fix merged, new fix incoming - @julow

Note - too many issues blocked on @jonludlam, need to rebalance! :-)

PRs open:

  • #478 (Top-level doc-comments of module types are discarded)

Octavius

Yet another issue cropped up with pulling the parser out of odoc and turning it into the new version of octavius - ppx_expect requires ppx_js_style, which requires octavius. We have just (2 weeks ago!) switched to using ppx_expect instead of the user-unfriendly expect tests we were previously using. Thus creating an octavius.opam within the odoc repo causes a dependency cycle (again!)

Solutions:

  1. Revert PR, stop ongoing work on moving more tests to ppx_expect.

  2. Disable expect tests on parser for CI for now, stop ongoing work on moving more tests to ppx_expect.

  3. Vendor current octavius into ppx_js_style and re-release.

  4. Make a package octavius2 rather than replace octavius, or call it something completely different

  5. Any other suggestions?

  • solution: have tests run by the odoc package rather than the octavius package

ocaml-docs-ci

@lortex has been continuing work on the pipeline presented last time. The repository now lives at https://github.com/ocurrent/ocaml-docs-ci and the voodoo repository is hosted at https://github.com/ocaml-doc/voodoo . @lortex is giving a deep-dive on the pipeline soon - details in the #docs-ocaml-org channel on slack.

Dune presentation

@lubega-simon will be giving a presentation in the dune dev meeting next week, Wednesday 14th at 4pm (?) on the odoc rules.

Next meeting

Thursday 22-04-2021

Clone this wiki locally