-
Notifications
You must be signed in to change notification settings - Fork 90
Dev meeting 2020 07 23
@jonludlam @trefis @avsm @Julow @lpw25 @drup
- @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
- 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.
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.
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