Dev meeting 2020 07 02
10:00am meeting this time!
Attending:
- @jonludlam
- @Octachron
- @Julow
- @lpw25
- @trefis
- @avsm
- @Drup
-
@avsm to investigate odig issue on docs.mirage.io @jonludlam to take over
-
@avsm to add toplevel support to merlin's roadmap
Lots of discussion about editor support for code fragments inside comments - should we have external files that are included, or should merlin understand toplevel fragments in comments? @avsm suggests including external files, @lpw25 mentions that lots of people in JS write toplevel expect-style tests. @lpw25 points out that mdx can now support testing of code fragments inside of comments in mli files:
https://github.com/realworldocaml/mdx/pull/206
Not enabled by default in JS because there is a worry about it being very slow. @lpw25 suggests completing this feature before starting a new feature.
Agreement that these are targetting different scale things - larger scale examples should be external - small things inline seems fine.
Need some dune integration to promote mli files.
- @jonludlam to find out status of dune build @doc supporting external libs
Not done
- @avsm to post on discuss about plans for replacing ocamldoc plugins
@jonludlam to take this one on.
- Model rewrite
PR: https://github.com/ocaml/odoc/pull/439
@lpw25: Review will be a while yet, but done some more testing, though hitting what's probably a compiler bug in compaction. Memory usage related to an early optimisation attempt that turned on eager evaluation when loading external roots. This is causing 75% of all allocations, and should be disabled.
@jonludlam: some other work being delayed while this is reviewed, suggest merging now and reviewing in master as, being a complete replacement, it's just as easy to review once it has merged. All agreed.
- LaTeX backend
PR: https://github.com/ocaml/odoc/pull/441
Works well to build the standard library, needs some testing on other libraries. Needs a little tidying but then can be merged.
- Memory usage
@Jules reported doing some testing of memory usage, found the 'eager' issue, but no other obvious low-hanging fruit.
It will be useful to have a 'reference driver' to show how odoc should be invoked, especially as that will be changing in the near future.
There was discussion about linking - odoc should be invoked to determine 'packages' to include during linking - this will be more obviously required when there is syntax for having cross-package links.
There was then some discussion about exactly what a package means. There are opam packages, dune packages and ocamlfind packages, and all of them differ slightly. There is consensus that the opam definition should not be the thing - @avsm reports that dune is likely to put in a back-link from the dune-project file to the opam package it came from, rather than having opam declare what ocamlfind/dune packages it contains.
@jonludlam reported some experiments related to the driver above to do with generating a docs.ocaml.org site with multiple versions of packages. The tricky thing is that a package version does not exactly specify what documentation will be generated, as it may include types/modules/others from other packages that are dependent on that packages version.
@lpw25 suggests the solution is to generate a hash of the dependent package versions - this will be less precise than than looking at the individual module level but it should be correct.
Not many large issues remain - mainly driving the build of the manual. @Octachron has been working on this, but it's currently not a great experience.
@lpw25 pointed out that there is a bit of a mess over mld files, and more generally about the hierarchy of packages (which odoc doesn't directly care about, it's just a tag given to a bunch of libraries). Odig works at the opam level not the ocamlfind level, which, as pointed out above, isn't a great way to do it. Odig has several heuristics to deal with the ambiguities.
@avsm points out the virtually useless package page, which just contains links to the entry points for each library. @lpw25 pointed out that this is where a hand-written package-level document should exist. If such a file does not exist, we could get rid and link directly from the package list possibly.
Example of the main page of packages:
Example of what you get when you click on yaml:
@jonludlam to write up a proposal for what to do with this.
16/07/20 10am
23/07/20 10am