Skip to content

Community meeting on docs.ocaml.org 2020 11 19

Jump to bottom
Jon Ludlam edited this page Nov 20, 2020 · 4 revisions

Community meeting on docs.ocaml.org 2020 11 19

Attending

  • @jonludlam
  • @lpw25
  • @avsm
  • @octachron
  • @AltGr
  • @Julow
  • @Drup
  • @rjbou
  • @dra27
  • @talex5
  • @thomasblanc

Presentation

@jonludlam gave a short presentation to set the scene

Demo

A prototype of the suggested content of docs.ocaml.org is available here, showing multiple versions of packages, links correctly going to the right versions, 'forward' links from a dependency package to a package that depends upon it (conduit 2.1.0 linking to conduit-async), and parallel universes where packages are built against different sets of dependencies.

Discussion

  • Results from the OCaml survey: everybody wants better docs!

  • Expected size of the artefacts: hundreds of gigs

  • Site is expected to be updated incrementally, however, is is very important that the site is 'reproducible' in the sense that in the unlikely scenario that we lost all of the artefacts, we would be able to reconstruct the site 'from scratch'.

    • will need to keep externally what solutions were found for each 'blessed' package
    • blessed packages are blessed forever, in an effort to keep the anchors on the pages the same.

  • Important that the pages are stable - such that the anchors are always there, particularly from the 'packages' URLs, not so much the 'universes' pages.

  • Using 'Marshal' to write odoc files is fine because it's 'forward compatible' - writing from an older odoc and reading from a newer one.

  • We want to, for all package versions, find a solution, install all the depopts possible, with the latest version of ocaml supported, and make a build graph. We then find the common overlapping subsets to minimise work.

  • Initial implementation is not worried about incrementalism, let's just manually do it first, then later see how we can make it incremental.

  • Plan was to prioritise release of odoc 2.0.0 - but new plan is to prioritise building an initial docs.ocaml.org based on the prototype

  • Possible extension of this is to diff between versions, to see what things change - @Drup said the document IR is diffable.

Plan

  • Use ocluster to build all versions of all packages - using opam-health-check as a starting point (which does largely the same thing).
  • Use the data gathered in this to get a good view of all the different types of package.
  • Get it live before the end of the year.
  • Need a monster machine and all the cmtis.
Clone this wiki locally