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!
How to help:
- Test browsing package documentation on staging.ocaml.org
- Report any bugs you encounter (even if it’s just a small visual issue)
Your testing helps ensure a smooth transition when these improvements go live. Thanks for helping us!
The ocaml.org and odoc maintainers
11 Likes
Thats great news !
I went to look at docs, and I have a few comments:
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.
I also think the line numbers are too large and bright, they’re not the main point here. Same with the link to the source in the main pages:
Cmdliner seems to lack sources: https://staging.ocaml.org/p/cmdliner/1.3.0/doc/cmdliner/Cmdliner/Cmd/Exit/index.html.
The sidebar has this small issue where the toplevel module is not being open by default:
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.
It might be bad for odoc to do that:
But I think odoc itself is very atypical. Most packages don’t have a dozen of libraries.
Maybe even display the parent and the child on the same line when thats the case, vscode does that for folders.
Jump to definition does not work across submodules of the same file which depending on the shape of the source can be very limiting.
My screen is very large, but I still have to scroll to see the end of that line:
Its 88 chars wide, maybe the source view could accommodate up to 120 ? I am not sure there is a great solution here.
Congrats for the great work, I am really happy that this is happening.
2 Likes
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.
I’ll see what I can do!
Cmdliner seems to lack sources: https://staging.ocaml.org/p/cmdliner/1.3.0/doc/cmdliner/Cmdliner/Cmd/Exit/index.html.
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.
Surely we can improve things here.
Rather, no one told me that I should.
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 ?
Something like opam reinstall $(opam list -s --all-versions --installed --depends-on topkg) should do it
1 Like
