# How to get pleasant documentation for a library using Dune?

**URL:** <https://discuss.ocaml.org/t/how-to-get-pleasant-documentation-for-a-library-using-dune/7121>\
**Category:** Learning\
**Tags:** odoc, dune\
**Created:** [January 20, 2021, 11:01am UTC](https://discuss.ocaml.org/t/how-to-get-pleasant-documentation-for-a-library-using-dune/7121 "2021-01-20T11:01:31Z")\
**Posts on this page:** 1\
**Showing post:** 3

<div class="post-metadata">

**Author:** ![gasche](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/gasche/32/4_2.png) [@gasche](https://discuss.ocaml.org/u/gasche)\
**Post date:** [January 20, 2021, 12:52pm UTC](https://discuss.ocaml.org/t/how-to-get-pleasant-documentation-for-a-library-using-dune/7121/3 "2021-01-20T12:52:19Z")

</div>

Thanks! It looks like these systems rely on an undocumented feature of the `(documentation)` stanza (or odoc), which is that a user-provided `index.mld` file will implicitly replace the automatically-generated `index.mld` file, giving a reasonably natural result.

The opium documentation also [uses](https://github.com/rgrinberg/opium/blob/2a89e35/opium/doc/index.mld#L72-L74) the `{!modules: modulename ...}` markup directive, which is a way to include the module index within this manually-written landing page without having to duplicate the markup. Streaming¹ uses [inline html](https://github.com/odis-labs/streaming/blob/ee5d82a/streaming/index.mld#L32-L68) instead to get a nicer-looking result, but it is too much effort. Maybe there is a better way, or the tools could be improved to make this easier.

¹: I’m ashamed to admit that I wasn’t aware of this very nice library [Streaming](https://odis-labs.github.io/streaming/streaming/index.html), am I consuming the wrong sources of information on the OCaml ecosystem?

Finally, the Opium documentation manifestly has a short synopsis for each module in its listing, which corresponds to my “It should briefly describe what each module does” requirement. I believe that this comes from the first line of the first documentation comment of the module. There are module-global documentation comments in the library I’m working on, but they do not include such first-line headers.

Once I have the impression of understanding what is a good way to do this, I may try to contribute better documentation in `dune`.

---

_[View the full topic](https://discuss.ocaml.org/t/how-to-get-pleasant-documentation-for-a-library-using-dune/7121)._