Which documentation generator for OCaml source code is the most user-friendly?

Ecosystem
,
1

Hey, dear community!

This time I could not found a good documentation generator for OCaml source codes so my question is:

Which documentation generator for OCaml’s source code is the most user-friendly?

What I mean by “user-friendly”?

  • HTML format is a MUST
  • Beautiful UI.
  • Great readability and highlighting for source codes
  • Links on definitions of modules and functions
  • It automatically adds signatures
  • It has a search over documentation
  • Extendable through plugins
  • Tabs for fast switching between many pages of documentation
  • Supports Markdown (yep, I want to use the pieces of Markdown in my comments)
  • It provides the ability for manual (through comments) linking between documents

P.S. Thank you very much for your help! You are (or, I hope we are) great community!

1 Like
2

Of course we are a great community! :smiley:

That’s a huge list of features! Have you used any code documentation systems that provide all of these? Could you show some examples?

Currently there’s a lot of new work being done on the official OCaml documentation generator called odoc. In fact it’s already being used by a large and growing number of packages. The system is built so that you can generate the package documentation locally from your machine (see how to acheive this with odig).

Unfortunately not everything you enumerated is currently implemented in odoc. Fuatures like search, plugin extensibility and markdown support are not present. But we are working on adding some of those. Here is a preview of a new visual theme with some of the features you asked for.

Does that look “user-friendly”? Let us know what you think.

4 Likes
3

Very nice indeed! Is this to be contributed to odoc?

4

@pveber It already has been, at least in git! See https://github.com/ocaml/odoc/pull/139 for a lengthy discussion.

1 Like
5

That’s a huge list of features! Have you used any code documentation systems that provide all of these?

I know that. It is a list of features that are wanted by me, but many of them are not mandatory. Ruby, for example has two pretty good tools: https://yardoc.org and GitHub - zzak/sdoc: Standalone sdoc generator and if OCaml has something similar to those two - it would be enough to me.

Does that look “user-friendly”? Let us know what you think.

It looks clear and easy to read.

6

A lot of effort is being put into improving the doc tools at the moment, but more assistance would be very welcome. You could help add the features you feel are missing.