`odoc` Documentation Improvements

Learning
,
1

The odoc team is working to improve the documentation, so we’re reaching out to the community to find out these things:

  • Are you using odoc? If so, how do you use it? What are your thoughts?
  • What parts of the documentation have been helpful?
  • What’s missing?
  • What suggestions do you have for improvement?
  • What are you pain points for either/both the documentation or the tool itself?

Your input is more valuable than I can express. Looking forward to your answers!

4 Likes
2

I think odoc and documentation writing, including .mld pages should be integrated in the language section of ocaml.org (likely around ‘Module System’/‘Libraries with Dune’).

The fact that the website has almost no mention of the fully integrated documentation system provided by the OCaml language is a shame in my opinion.

The documentation is fine for me but I’m likely an outlier, having spent the last 20 years writing ocamldoc :–) I think that @panglesd recent cheatsheet significantly lowers the barrier to jump into ocamldoc writing. However the question, which resonates with my comment above, is how people are going to find it. Most people will likely not consult odoc’s documentation pages.

Regarding the tool itself we are, with the upcoming introduction of assets, about to reach perfection, but there is this.

3 Likes
3

My quick two-buck feedback on using odoc:

  • Error reporting is unusable.

    • For one, each error is often reported multiple times (issue #1127) (if there is an error in a module type, it will be reported for each time the module type appears, modules with that signature, module types which include it, modules with signature of those module types…). This spam output a lot.
    • Furthermore, the output spam is made worse by the warnings that appear when using standard library stuff (issue 1120 as mentioned above).

    For reference on how bad it gets, I have a lib which has 9 @raises Not_found in the mli. Running dune build @doc yields 376 lines on stderr (at two lines per error that’s 188 errors), for something which should yield zero.

  • doc-json: when using odoc I quickly wanted to integrate the generated content in my own website. dune build @doc-json is (almost) perfect for this, however I only learned of it through discussion with colleagues. It doesn’t seem to be documented anywhere, which is a shame. I remember reading the doc looking for just this and only finding the driving odoc page which seemed far too technical for what I wanted to achieve (a.k.a. get the documentation body).

  • I would also appreciate a few extra fields in the json:

    • title: the only way to get page title currently is looking at the last breadcrumb’s name
    • package and version (package can be obtained from the path for now, version must come from external information (git ref).
    • objects a list of all objects defined in the current file (vals, modules, …).
    • a field to indicate the path to db.js if sherlodoc is installed maybe?

  • Similarly, odoc now integrates a nice search bar if sherlodoc is installed. I’m not sure if this is mentionned in the documentation, but it should. I only learned of it through an ocaml discuss post.

  • It would also be nice if the odoc documentation mentioned mdx. It allows executing the code in documentation to check the generated outputs, which is a very useful feature.

  • @raise Not_found if bla bla is rendered with a newline between error name and description, I find this weird and unintuitive, but its easy enough to patch with CSS.

  • An option to open modules in documentation would be useful. For my library, I have a single module and an index.mld file. In that mld, all my references are either MyLib.foo, which clutters the doc, or {{!MyLib.foo}[foo]}, which is annoying to write.

4 Likes
4

Thanks. It’s actually documented here but it could use some links to it. If you can open a dune issue about this, I’ll get to it.

1 Like
5

Done: Better documentation for `@doc-json` · Issue #10557 · ocaml/dune · GitHub

2 Likes
6

Thanks @dlesbre, this is very useful feedback. Can I suggest up front that you turn these into issues on ocaml/odoc? (I know you’ve done the first one – thanks!) I’ll address some of the individual points you mention here though:

  1. Error reporting is unusable
    Yep, it’s not great today. However, the first thing to try, if you’re using dune, is dune build @doc-new. This is the experimental target that builds docs for your library and its dependencies. It’s not widely advertised today as we’re expecting to change some aspects of how it works, in particular the layout of the generated HTML, but for the purposes of checking for errors in your docs it should be much better.

  2. doc-json
    The doc-json output is what we use for ocaml.org, and is designed so that you can embed the output in other pages. As far as the extra fields that you mention go:

  • title - easily done.
  • package and version - not so easy, because odoc doesn’t know (and doesn’t care!)
  • objects - we’re likely to create a separate index file that will contain this info - this is part of the work to create a useful sidebar.
  • db.js - sure, why not.

  1. sherlodoc and mdx
    We should definitely mention both sherlodoc and the mdx integration. I’m glad you’re finding both features useful.

  2. @raise
    The rendering of tags could definitely do with some love. This is one of the most straightfoward thing in your list, and I’d be very happy to see PRs in this area :slight_smile:

  3. opening modules in mlds
    That’s an interesting suggestion. We’ve got something like this on the CLI, but it’s not accessible if you’re building with dune. We’re intending to have some sort of ‘frontmatter’-like block, this is potentially something that could go in there?

3 Likes
7

Ok so here are all the issues:

3 Likes
8

I found it surprising that there are new warnings with the ‘@doc-new’ target, so I had a bit more of a look. It turns out they’re not new in some sense; the ‘@doc-new’ target builds the docs for everything including private libraries, and the ‘new’ warnings are just those you get when building the ‘@doc-private’ target.

I’m going to spend a bit more time next week looking into the issue of the underlying cause of these warnings though.

1 Like