[ANN] Odoc 3 Beta Release

On behalf of the odoc team, I’m thrilled the announce the release of odoc 3.0.0 beta 1!

This release has been cooking for a long time - it’s been more than a year since odoc 2.4 landed, and a huge amount of work has gone into this. Thanks to the many others who contributed, either by code or by comments: @juloo, @panglesd, @EmileTrotignon, @gpetiot, @trefis, @sabine, @dbuenzli, @yawaramin, and more.

With this release we’re including a driver that knows how to use all of the exciting new features of odoc. This driver has been used to create the docs site for the various odoc tools.

Here are a selected set of features:

  • :droplet: Rendered source! Jump from any item in the documentation straight to its rendered source; no matter how much of OCaml’s complex module system you are using.
  • :mag: Search by type! Our detective sherlodoc will find your lost value given its type.
  • :warning: Convenient warnings! Warnings are now clearly visible and useful, no longer buried among your dependencies’ warnings.
  • :arrow_heading_up: Self host your documentation, but link to ocaml.org for your dependencies.
  • :100: More sidebars! Odoc 3 features a global sidebar, allowing you to discover the most hidden corner of underground documentation.
  • :exploding_head: Image support! This cutting-edge feature now allows you to add images to your documentation. Video and audio come for free.
  • :spider_web: Fully cross-package links! The OCaml docs are now a true spider web. Prepare to catch bugs, and eat them.
  • :cop: Hierarchical documentation pages! We use a modular language. We don’t want a flat namespace for pages.
  • :building_construction: The build dependencies are friendlier with incremental build systems, allowing better shared build caches.
  • :heart: Quality of life improvements! Many improvements have been piling up since we started odoc 3. For instance: Add clock emoji before @since tag (@yawaramin, #1089)!

More explanation of these features is available at the odoc site, where we have documentation for authors, for users of odoc_driver, a cheatsheet, and differences from ocamldoc.

How can you help?

We need your feedback, both as authors and as users of documentation! Try things out using the new driver:

$ opam install odoc-driver    # don't forget to `opam update`
$ odoc_driver <package list>  # For instance: `$ odoc_driver brr odoc`
$ $YOUR_BROWSER _html/index.html

Many of those features’ implementations are not set in stone, but first versions. Please leave comments, either in this thread or as issues in the repository.

So, navigate already written documentation, and update your own docs to use the new features!

44 Likes

For my project I used odig odoc ... to generate documentation. Should I expect that new changes in odoc will be applied when I call command mentioned?

First of all, congratulations on this beta! The list of features is very exciting!

I tried using odoc-driver (with odoc 3.0.0~beta1) at the root of the YOCaml project: GitHub - xhtmlboi/yocaml: YOCaml is a static site generator, mostly written in OCaml And I’m a bit circumspect because I have the impression that all the documentation except that of the packages related to YOCaml doesn’t get built.

odoc                     3.0.0~beta1  OCaml Documentation Generator
odoc-driver              3.0.0~beta1  OCaml Documentation Generator - Driver
odoc-md                  3.0.0~beta1  OCaml Documentation Generator - Markdown support
odoc-parser              3.0.0~beta1  Parser for ocaml documentation comments
sherlodoc                3.0.0~beta1  Search engine for OCaml documentation

For example, using odoc_driver yocaml yocaml_eio gives that list:

    angstrom
    base
    base-bigarray
    base-bytes
    base-domains
    base-threads
    base-unix
    base64
    bigarray-compat
    bigstringaf
    camlp-streams
    cohttp
    cohttp-eio
    conf-bash
    conf-pkg-config
    cppo
    csexp
    cstruct
    digestif
    domain-local-await
    dune
    dune-configurator
    eio
    eio_linux
    eio_main
    eio_posix
    either
    eqaf
    fmt
    hmap
    http
    iomux
    jane-street-headers
    jst-config
    logs
    lwt
    lwt-dllist
    magic-mime
    mtime
    num
    ocaml
    ocaml-base-compiler
    ocaml-compiler-libs
    ocaml-config
    ocaml-syntax-shims
    ocaml_intrinsics_kernel
    ocamlbuild
    ocamlfind
    ocplib-endian
    optint
    ounit2
    parsexp
    ppx_assert
    ppx_base
    ppx_cold
    ppx_compare
    ppx_derivers
    ppx_deriving
    ppx_enumerate
    ppx_expect
    ppx_globalize
    ppx_hash
    ppx_here
    ppx_inline_test
    ppx_optcomp
    ppx_sexp_conv
    ppxlib
    ppxlib_jane
    psq
    ptime
    re
    result
    seq
    sexplib
    sexplib0
    stdio
    stdlib-shims
    stringext
    thread-table
    time_now
    topkg
    uchar
    uri
    uri-sexp
    uring

What did I miss?

No, drivers like odig (and dune) will have to be updated to make use of the new features. We do aim for backward compatibility though, so if odig doesn’t work with odoc 3, that’s likely an odoc bug that should be reported.

I suspect what’s happening is that you’ve got all the dependencies of yocaml installed in your switch, but not yocaml itself - by default odoc_driver only looks at installed packages. However, you can get odoc_driver to pick up the package from dune’s _build/install directory - try

$ dune build @install
$ dune exec -- odoc_driver yocaml yocaml-eio

and see if that works?

This is probably a sufficiently likely scenario that we ought to warn about it - I’ll get that in for the 3.0 release.

3 Likes

It is working! Thanks!

The warnings improvements are, I think, one of the most immediately useful of the new features. As a motivating example, I’ll use the patricia-tree package. Checking out the v0.11.0 tag and building the docs with dune build @doc, you get:

➜  patricia-tree git:(v0.11.0) ✗ dune build @doc
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 129, character 0
While resolving the expansion of include at File "src/functors.mli", line 199, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 214, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 129, character 0
While resolving the expansion of include at File "src/functors.mli", line 199, character 2
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 209, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 129, character 0
While resolving the expansion of include at File "src/functors.mli", line 199, character 2
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 129, character 0
While resolving the expansion of include at File "src/functors.mli", line 199, character 2
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
While resolving the expansion of include at File "src/signatures.ml", line 198, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 766, characters 6-23:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 129, character 0
While resolving the expansion of include at File "src/functors.mli", line 183, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 761, characters 6-23:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 129, character 0
....
hundreds of repetitive lines removed
...
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 209, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
While resolving the expansion of include at File "src/signatures.ml", line 198, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 214, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 209, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
While resolving the expansion of include at File "src/signatures.ml", line 623, character 2
While resolving the expansion of include at File "src/signatures.ml", line 198, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 214, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 209, characters 6-43:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
While resolving the expansion of include at File "src/signatures.ml", line 198, character 2
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/signatures.ml", line 174, characters 6-51:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 125, character 0
Failed to resolve reference unresolvedroot(Not_found) Couldn't find "Not_found"
File "src/ints.mli", line 63, characters 16-23:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 121, character 0
Reference to 'mask' is ambiguous. Please specify its kind: type-mask, val-mask.

The vast majority of this is entirely unfixable as the errors aren’t really related to the souce of the project. In contrast, with odoc_driver, you get:

➜  patricia-tree git:(v0.11.0) ✗ dune build @install
➜  patricia-tree git:(v0.11.0) ✗ dune exec -- odoc_driver patricia-tree
Deciding which packages to build...
Performing module-level dependency analysis...
Starting the compilation process...
Documentation generation complete. Results are in _html/
Output from commands:
/var/folders/n6/tnqs3c8x4y522ymyy2xgvd6c0000gn/T/odoc-4ff9ce/patricia-tree/patricia-tree/patriciaTree.odoc
----------------------------------------------------------------------------------------------------------
File "src/ints.mli", line 63, characters 16-23:
Warning: While resolving the expansion of include at File "src/PatriciaTree.mli", line 121, character 0
Reference to 'mask' is ambiguous. Please specify its kind: type-mask, val-mask.

And here the warning is very fixable.

5 Likes

Is the update of dune build @doc for odoc 3 features planned/being worked on, e.g. by the time for the non-beta release?
Obviously that’s a dune thing, but it would be shame to have to switch workflows from dune build @doc to odoc_driver (and later back when dune support exists).

We do expect to work on the dune rules, but I’m not going to guarantee they’ll be ready by the time we’re happy with odoc 3 - the new rules will be significantly more complex than those in dune already, both @doc and @doc-new.

However, we do expect to be completely backward compatible, so if you continue to use the odoc 2.x features then dune will continue to work.

Our immediate focus is on ocaml.org, because I see the lack of support there as more of a blocker - you can choose between using ‘dune build @doc’ and using ‘odoc_driver’ but there’s only one ocaml.org!

Good work! While updating the documentation for server-reason-react I found a few doubts:

  • is there any feature planned on search by content for the entire documentation site?
  • does odoc-driver support watch mode?
  • is there any way to exclude generating the documentation for all my dependencies?

This might be a little outdated, but as far as I remember :
Search by content for the entire site is probably a one line change. It used be activated, but I think we did not like it that much and turned it off (the search index is compiled to JS and can get pretty big).
No watch mode for odoc-driver, it recompiles everything each time so it would not make sense. Its not supposed to be new build system. If you have a very fast documentation build, I think there is a unix command to make any command into watch mode.

For excluding the dependencies I don’t know.

  • Not right now, but it wouldn’t be hard to change this if it’s desirable. As @EmileTrotignon said, the default today is client-side search (as odoc is intended as a static site generator), and the search index can get quite large. It also probably wouldn’t be a huge amount of work to use sherlodoc server-side, as it is on https://doc.sherlocode.com, but we’ve not spent much time thinking about this yet.
  • No, but the plan is to update the dune doc rules to match those in odoc_driver so that’ll happen then. We’ve made some changes to how odoc is invoked to ensure it plays nicely with the dune cache, so that’ll make things even nicer.
  • Yes - run odoc_driver server-reason-react --remap and it should only generate the HTML for server-reason-react. As a bonus, any links that would have gone to your dependencies should now go to ocaml.org instead.
3 Likes