How to document an ocaml application

Learning
1

I’m struggling to understand how to use odoc to generate documentation for an application built with ocaml. I don’t want to document a library that others are going to use, rather I want to document the various modules that were created to support an application. I’ve tried using doc-private with limited success. What am I missing? Is creating documentation for all the code that I write not possible using dune?

2

One commonish pattern is to structure your application as one or several “libraries” (in terms of how you define them with dune) and then a thin single file for the executable.

1 Like
3

Hi, @TodAmon! As @roddy suggested you can create a local library and use it in your executables to document the various modules of your project.

I created a small project that illustrates this in practice: https://github.com/rizo/ocaml-by-example/tree/main/basic-lib-doc

Please let me know if you manage to get this working! :slight_smile:

4 Likes
4

Thanks rizo, works great! This is a big help. Much appreciated.

5

Hi @rizo I submitted a minor change to the project to obtain documentation for a library. It works fine, but brought up an important question. How to use odoc to get hierarchical documentation? E.g., when our sample application (for which we created a local library) depends on local libraries. We want those libraries documentation to be under the local library. Right now, the public names for libraries can include hierarchy, but it is ignored (e.g., the “.” is just part of the name).

I was very happy to see that odoc would pick up documentation from a local libraries “.ml” file if there was no signature.

To be specific, the odoc that gets created essentially shows all libraries at the top level.

This will definitely meet my immediate needs.

6

I appreciate your work guys and the answers in this topic, for me it is a new but useful information and I can safely put it into practice in the future. :slightly_smiling_face:Thanks!

7

Hi @TodAmon!

We’re working now on allowing odoc to represent hierarchies better - there is some documentation on the approach on the odoc wiki. Once we’ve decided on how odoc will deal with this we’ll then need to update dune to be able to represent the docs in this way.

Just to be clear on what you want though, you’re talking about libraries with something like (public_name package.foo)?

2 Likes
8

Thanks @jonludlam

Yes, exactly. Bottom line what I would like to be able to do using odoc is document an application from the top down. Introduce readers of my code to what the code is doing, how it is broken up. For each library, what its purpose is. For each module what its purpose it. I’m still struggling to see how to accomplish this goal with “dune build @doc” – it would be nice to add documentation to index pages for example. E.g., my “readers” now start at “OCaml package documentation”, if they drill through the index pages, they can eventually start see my descriptions about libraries, modules, etc. I am not quite able to tell a “hierarchical curated story” about the application and is libraries yet. Thanks for your work.

2 Likes