Odoc 1.4.0 — new OCaml documentation generator

Community
,
#1

We are pleased to announce release 1.4.0 of odoc, the new, Dune-friendly documentation generator for OCaml and ReasonML.

Some sample output, which you can browse here:

odoc-output
odoc-output.PNG1276×822 94.6 KB


You can install odoc and generate docs for your Dune project with:

opam update
opam install odoc
dune build @doc

Then, view the docs by opening _build/default/_doc/_html/index.html!


While release 1.4.0 has new features, it is mainly focused on stability and maintainability. See its full changelog here. The previous release, 1.3.0 last October, included a lot of new code. Because of concerns about its stability, we chose not to widely announce 1.3.0. So, this message serves as an announcement for both releases :slight_smile: The full changelog for 1.3.0 can be found here.

In summary, compared with 1.2.0, odoc now has:


For now, we plan to continue improving the stability of odoc and the quality of its output. In the longer term, odoc has two significant goals:

  • To replace ocamldoc as OCaml’s primary documentation generator. At the core of odoc is a powerful cross-referencer, capable of fully handling the complexity of OCaml’s module system. Shortcomings in ocamldoc’s ability to resolve cross-references in complex projects were one of the original motivations for starting odoc.

  • To create centrally-hosted, cross-referenced, searchable online documentation for all the published packages in opam, a “docs.ocaml.org.”


Thanks to the odoc users and contributors, and happy documenting!


43 Likes
#2

Exciting stuff! The new output looks great.

y

#3

Thanks, a large proportion of the improvements in visual quality is due to the work of @rizo :slight_smile:

7 Likes
#4

I think it is also worth showing the styles Daniel has done based on the new markup, which are also pretty nice:

https://b0-system.github.io/odig/doc@odig.dark/alcotest/Alcotest/index.html
https://b0-system.github.io/odig/doc@odig.light/alcotest/Alcotest/index.html
https://b0-system.github.io/odig/doc@odig.gruvbox.dark/alcotest/Alcotest/index.html
https://b0-system.github.io/odig/doc@odig.gruvbox.light/alcotest/Alcotest/index.html
https://b0-system.github.io/odig/doc@odig.solarized.dark/alcotest/Alcotest/index.html
https://b0-system.github.io/odig/doc@odig.solarized.light/alcotest/Alcotest/index.html
https://b0-system.github.io/odig/doc@odoc.default/alcotest/Alcotest/index.html

(that last one is the new odoc default for comparison)

15 Likes
#5

Wow, this looks amazing. A whole new level of looking. Would be nice to update Core/Base documentation with this tool. I don’t think the current look of e.g. https://ocaml.janestreet.com/ocaml-core/v0.12/doc/base/index.html is good. Especially color palette.

#6

Reusing the tool for the OCaml reference itself would be cool too, the current state of the http://caml.inria.fr/pub/docs/manual-ocaml/core.html is just plain awful. I bet it shies away the modern generation got used to nicer looking documentation with JS/CSS shenanigans. Haskell has similar problem too… Just compare with Rust official reference book https://doc.rust-lang.org/book/ch03-05-control-flow.html

2 Likes
#7

JaneStreet’s documentation has precisely been updated with this tool. If you are unhappy with the theme they choose you can simply:

opam install ocaml-manual base odig
odig odoc-theme list # spot the theme id you'd like
odig odoc-theme set --default mytheme
odig doc base

Regarding the OCaml API reference just odig doc ocaml and if you install the manual as above it will theme accordingly (see for example here for the manual themed according to odig.light — though the api reference that comes with the manual itself doesn’t, just use the odig generated one).

If you are still unhappy about the selection of themes just provide your own and distribute it via opam.

4 Likes
#8

Doesn’t work for me. It exits silently with status 0.

here is the “_build/log”:

# dune build @doc
# OCAMLPARAM: unset
$ /usr/bin/nproc > /tmp/dune771d0a.output 2> /dev/null
$ /home/freyr/.opam/main/bin/ocamlc.opt -config > /tmp/dune7d5f8f.output
#9

Can you make sure the latest version of odoc is installed (run odoc --version)? What is the dune version? Do you have any mli library files in your dune project?

#10

dune 1.8.3, odoc 1.4.0

Yeap, I have mli’s. BTW should dune build @doc also generate docs for dependencies?

#11

That’s strange. Could you open an issue on odoc’s GitHub that includes a minimal project (ml/mlii and dune files) that has this issue?

BTW should dune build @doc also generate docs for dependencies?

No. That’s what odig should be used for. Once your package is installed locally (with for example dune install), you can use odig to generate its docs and that will include dependencies.

#12

That’s strange. Could you open an issue on odoc’s GitHub that includes a minimal project (ml/mlii and dune files) that has this issue?

I’ll try.

No. That’s what odig should be used for.

I thought it should generate doc for both my libraries and their dependencies. Odig is not very convenient since it generate docs for all packages in my switch. It would be nice for development purposes to be able to generate docs for all libraries in the project and their dependencies. Cargo can do it AFAIK.

#13

Not necessarily. See odig odoc --help.

#14

Ok, another question: does dune build @doc builds docs for non-public libraries?

#15

No, you have to use dune build @doc-private.

#16

Well, yes, I could build doc for dependencies, but I can’t build it for private libraries in my dune project, right?

I’m looking for direct analog of cargo doc, which could build and show docs for all libraries in the project and their dependencies.

#17

Ah, yeah, indeed. I wish it could generate docs for deps as well though. It’s inconvenient to generate separate docs for project with dune and dependencies with odig.

#18

I don’t think that’s the problem of odig but you can have a look at this issue for a hack.

Regarding your desire, you’ll have to check with dune's developer but I think there are basically two approaches: either dune takes care of building all the docs itself or it only builds the docs for the libraries it builds and allows to specify an existing docset to link into, the technology for this is not there yet though, see this issue.

#19

Thanks. Yes, I think it’s a problem and a purpose of dune rather than odig.

either dune takes care of building all the docs itself or it only builds the docs for the libraries it builds

Considering it already tracks the dependencies and builds the docs for local packages, it seems natural to merge these two and build docs for dependencies as well, but maybe there are some hidden issues I’m not aware about.

#20

Please do create an issue on the Dune repo so this usecase can be tracked properly. There is still some work to be done on the dune/odoc rules, but it’s progressing.

2 Likes