Document odoc, help people write good docs

[aantron]

This issue is about improving odoc's documentation, and documentation about writing documentation in general.

To get started:

• Link to @bobbypriambodo's documentation guide from the README.
• Explain how to create overall complete documentation for a project, apart from just an API reference. This means documentation for .mld files. Links to well-documented projects would be useful here.
• odig usage instructions.
• Fully document the grammar of comments accepted by odoc.

Suggestions from https://discuss.ocaml.org/t/1841/56, https://discuss.ocaml.org/t/1841/68, https://discuss.ocaml.org/t/1841/78. The README already has some of what was suggested, such as Jbuilder+odoc usage instructions. But, please say if this needs to be moved, clarified, etc. :)

We should probably generalize odoc more away from Jbuilder at some point (e.g. towards bsb). At that point, or earlier, we will also need good documentation on how the odoc command-line tool works.

[tomjridge]

I'd like to use odoc rather than ocamldoc. But I don't use jbuilder. I can use odoc manually, but lots of things are not quite right - eg module links, missing index pages etc.

So I support more documentation on how to use odoc for people not using jbuilder!

[aantron]

@tomjridge Agreed.

A short-term hack would be to run jbuilder in verbose mode, and see what it commands it issues and in which directories.

Obviously, that's not a substitute for a stable interface and real docs.

[lubegasimon]

This must be fixed via #733, and the site is https://ocaml.github.io/odoc/

[dbuenzli]

As @lubegasimon mentions, there has been progress on this. Let's open more specific an actionable issues if things need more improvement on that front.