We’re in the process of deploying odoc 3 on the package documentation pipeline that underpins the package documentation pages at OCaml Packages · Browse Community Packages.
We’ve prepared a patch for OCaml.org that renders the packages’ documentation pages with the new odoc 3 features. Before deploying this on the production version of the OCaml.org website, we’re looking for community feedback on the updated package documentation pages now available on staging.ocaml.org.
Some of the new odoc 3 features benefit all packages!
The docs CI is now using a new driver, with many more docs being built. Compare the docs for yojson in the old and new CI!
The docs now features a “source” link next to most items, taking you to a rendered version of the source code. For instance, if you wonder how the List.sort_uniq function is implemented, click on the source link next to it!
The sidebar and breadcrumbs, which were previously hacked together by ocaml.org, are now properly generated by odoc. Compare odoc’s old and new sidebar!
The URL layout has been updated to include the library names, with redirections to avoid dead links.
Some other new features opens new possibility for documentation authors! They are mostly unused as their support is so recent, but you can test then on odoc’s docs:
Ocaml.org now allows to reference other packages modules and pages! For instance, odoc-driver’s doc, in its introduction, references a page from sherlodoc’s doc! It’s as simple as this syntax.
Medias, such as images, finally work on ocaml.org. This requires using the special syntax that is so new that, currently, only odoc’s cheatsheet is using. But since we made sure to be compatible with odig’s convention, images now work for several packages: compare Vg’s tutorial before and after!
I understand that for packages with multiple submodule you would not want to, but its probably possible to have modules be open by default when they are the only child of their parent.
Thanks a lot Emile for the valuable feedback! And for your help on odoc 3.
I’ll try to fix those issues before we merge then. (About the “visual” comments I have a disclaimer: I’m very not a designer, so I’ll do my best but … if anyone wants to help with a PR?)
This does not look very good because its multi-line. Also the color highlight is not part of the color scheme which makes feel it a little off.
For a package to have source displayed, it needs to install the .ml. dune does this by default, so most packages get rendered sources. However I don’t think @dbuenzli’s packages do that. I don’t know if that is a choice to avoid having users depend on implementation details?
The sidebar has this small issue where the toplevel module is not being open by default:
As you point out, it’s hard to make the sidebar look good on most cases…
Its 88 chars wide, maybe the source view could accommodate up to 120 ? I am not sure there is a great solution here.
So, once this PR is merged, to have your source be displayed in the docs, you need to install the .ml corresponding to your compilation units in order to have source rendered in the ocaml.org website!
I think this should be added to the documentation, with more details. I’ll open an issue.
(Note that I often end up in my opam switch by following merlin, and sometimes I use the installed source to look up for examples or other info on the API. This is not possible for packages which do not install source, which is not bad enough for me to open an issue. But I would be happy if your packages do install sources!)
Except for cmdliner whose distribution is based on a Makefile so that it only depends on ocaml, that’s an issue with topkg, not with individual packages. Opening one there increases the chances that I don’t forget.
I don’t think it should be too hard to add (it’s already done with for .mli files). There’s likely just a few subtelties with packed modules (manually with .cmi hiding, not -pack) and/or module aliases, but unless I’m mistaken this should be a matter of mimicking the install logic that is in place for .cmx files.
Btw. anyone knows if there is an invocation to retrigger package that build depend on topkg in an opam switch ?
However, even with the distinct color, I still think this layout is a bit confusing. I would consider moving this link to above or below the function signature, or also adding a distinct background color.
Thanks @dlesbre for your feedback! I have updated the style for the “link to source” button as per Emile’s comments, unfortunately it has still not yet been pulled on staging. I’ll ping @sabine about this.
While the new style will definitely be better, I haven’t tested properly on mobile. I’ll work on that!
I’ve just triggered the deployment of the current state of the PR (52d1860) to staging.ocaml.org, which includes fixes based @panglesd has made based on your reports.
The patch should be live in around 15 minutes. (Random trivia: you can check OCurrent Deployer to see the build logs and how the deployment is coming along.)
Notice that the badges are displayed here on separate lines, with weird quotation " symbols in between them. The expected output is visible in the github render of that same readme:
.
