Skip to content

Dev meeting 2020 07 23

Jon Ludlam edited this page Jul 23, 2020 · 5 revisions

Present

@jonludlam @trefis @avsm @Julow @lpw25 @drup

Actions from previous meeting

  • @avsm to investigate odig issue on docs.mirage.io @jonludlam to take over

Build succeeds (with a few odoc failures)

Results are: https://www.cl.cam.ac.uk/~jjl25/docs.mirage.io/html/

  • @jonludlam to find out status of dune build @doc supporting external libs

Not done

  • @jonludlam to post on discuss about plans for replacing ocamldoc plugins

Not done

Status update

  • New model merged
  • Testing on JS internal libraries

Highlighted some issues, particularly around memory usage. Two main issues: that paths are often being resolved multiple times, resulting in exponential increase in size for particular constructs. Secondly that the construct include module type of struct include Foo end ends up with two expansions (one on each include) that again leads to exponential size increase. Both of these issues are fixed by https://github.com/ocaml/odoc/pull/442 - @lpw25 to review before merging.

  • Latex backend merged
  • Reference driver

There was discussion about the purpose of the reference driver. @avsm wondered about extending its scope to be 'feature complete', and effectively becoming a replacement for odig. @lpw25 was worried this would turn into it becoming a new build system. @trefis suggested that the reference should be documentation rather than executable. @jonludlam stated that the initial need was in order to test the new commands (link/generate), and for use in an integration test suite. There was agreement in the end that the primary goal of the reference driver should be to build the OCaml manual.

Outstanding PR review

https://github.com/ocaml/odoc/pulls

  • Refactoring CLI

Some outstanding questions on drivers, in particular the 'html-targets' command. @drup likes manifest solution, but jenga (and other build systems) can't support manifest solution very easily. @jonludlam: generating accurate output should be straightforward to from the linked odocl file. @jonludlam to take a look at doing this.

Also, should this be a new major version? @lpw25 suggests dropping support for the old CLI commands on release. @jonludlam wants to keep them while development is going on.

There was discussion about what the oldest compiler that we support today is, and how painful keeping that is. 'Not very painful right now' was the general consensus - travis does a good job of telling us when older versions break. @avsm was wondering about using odoc as a test case for multicore - @lpw25 wasn't convinced as it's pretty trivially parallel already, working on different files. It was suggested that Merlin has similar issues to odoc when it comes to supporting older versions, so we should keep an eye on what Merlin does.

  • Several Reference resolution related PRs from @Julow

These all look good, with some minor issues (rebasing/fixing breakage on older OCamls)

  • Functors rendering

Just needs review of output, but is otherwise good to go

  • Optimisations PR

Discussed above.

'Replacing Ocamldoc' milestone issue review

https://github.com/ocaml/odoc/milestone/5

  • @Julow to pick up CSS issues
  • Notion of 'Scope' - need an 'initially opened module' argument to open 'Stdlib'
  • --keep-code - remove as previously discussed
  • latex/math support - want to pass through latex to the latex backend, don't necessarily need anything else for the HTML backend yet
  • Several new-model related issues
  • 'New framework for integration tests' - looking at using mdx for these

@drup pointed out that we're missing an issue for the module index missing command.

This prompted some discussion on packages/libraries. The discussion continued in the #odoc-dev channel on slack for a while, with the conclusion:

lpw25: I think we just say that any module can be given a "parent" that is a page
       and pages are passed the list of their children
       The only effect of this is to change the identifier for the module to have the page above it
       and so that asking for a modulelist on a page works
       but that will also allow things like the side bar to work
       Then we adjust dune to create such a page when building a non-namespaced library

jonludlam: @drup does this address all of your concerns?

lpw25: The only other aspect of a non-namespaced top-level module which you might want to replicate is that there is a point in the module that corresponds to each of its children
       You could imagine having a {!child: Foo} ref or similar that would add something like:
       module Foo : sig ... end
       and show up in the side-bar as Foo
       That would allow you to write your page like:

This is the foo library
{1 The first part}
These modules do the first part
{!child: Foo}
{!child: Bar}
{1 The second part}
These modules do the second part
{!child: Baz}
{!child: Foz}

       And it would give you a side-bar like:

The first part
 Foo
 Bar
The second part
 Baz
 Foz

       And I guess that we just add any children that don't have a {!child: ...} ref at the bottom of the side-bar in the order they appeared on the command line

drup: Sounds promising, let's try and see

lpw25: This all also rather begs the question of whether we could eliminate the notion of "package" from odoc and just use pages as parents instead

drup: That seems like the natural next step

lpw25: That would definitely have some benefits

jonludlam: neat

lpw25: We'd just eliminate the -package option
       and the support for index.mld being the page for a package
       I guess it would mean that rules like: Canonical paths must be within a package, would need to be reformulated in terms of parents
       Those were already going to need some adjustment if we added a notion of library anyway
       Taking all those rules are replacing "within the same package" with "has the same parent" should be fine
       e.g. The deps specified by link-deps would now be a list of pages whose children a module depended on

jonludlam: this'll be fun
           definitely 2.0 

Next meeting

2020-08-06