Dev meeting 2020 12 17

Agenda

Attending

• @jonludlam
• @lpw25
• @Drup

docs.ocaml.org

Focus has been on this since the community meeting.

Preview site here

• ~13000 builds
• 9 gigs of tarballs full of cmt, cmti and cmi files
• compiled odoc/odocl files total ~40 gigs
• 15 gigs of html in packages/
• 23 gigs of html in universes/

Subpackages

Currently the package pages are just the list of top-level modules exposed in the package and all of its sub-packages. How to separate this usefully?

See e.g. ocaml-base-compiler for an example of an awful page

Agreed approach: List the modules in cma/cmxa files to categorise modules into different libraries

Strategy of linking

• We wanted to have stable links
• That doesn't necessarily mean the links under package need to be stable
• e.g. github links - you can link to master but that's not necessarily stable - if you want a stable link you hit 'y' first to set the URL to the specific commit
• We could do this by always generating the html under universes even for 'blessed' packages (meaning duplicate of ~15 gigs of html right now).
• Advantage is that 'stable' packages don't alway point at older versions of ocaml/other libs

@Drup: good idea - look up software heritage project https://www.softwareheritage.org/ - they might have some

Others

• Need to enable escaping of references - so we don't have to have versions like '1_2_3_1' rather than '1.2.3-1'

Styling:

• doc comments appear closer to the wrong thing than the right thing - vertical alignment
• functions with labelled or many args look bad
• module types with with with look bad

Odoc

• CI fixed (again!)

PRs progress

• Parent/Child PR - need some improvements as pointed out by @Julow - specifically the --child CLI argument needs to take 'page-' prefixes to specify pages. For consistency we'll probably do the same for --parent

• @Julow found and fixed a nasty subst error that was producing incorrect types for some modules - notably the Monad module in Base PR

Next meeting

Thursday 14th January?