The problem is that, in the current state of affairs you will likely get redundant information and irrelevant contextual information. I’d rather have that as a separate link.
Having a lot of published packages (~40) I faced quite early the problem of redundant information to specify and can’t afford spending time on churn – which is only concomitant to the software practice if you decide to accept it. Just to give an idea these “oh it’s just five minutes of your time on your package” become 3h of soulless work for me.
So in the scheme I designed for topkg’s release process, later reused by dune-release. The idea was the following, if you don’t specify an opam synopsis and/or description yourself it is derived from your README as follows (atx headings or asciidoc are also supported):
$(NAME) $(SEP) $(SYNOPSIS)
--------------------------
$(DESCRIPTION)
# First header of any level
Now that works very well for opam.
However the thing is that in $(DESCRIPTION) may want to link in your package docset. This desire extends more generally if you try to use your README as your documentation (personally I don’t think that’s the place, simply have a link to your package docset in there).
The problem is that you can’t make this to work both on github and other documentation generation context – and I urge people to devise their docs so that are perusable in any documentation context, for reasons that go from offline perusal (e.g. air-gapped settings, retreats, etc.), to accessibility, to the possibility of having docset generated locally only for those package you use in your project, etc.
Since I couldn’t reuse $(DESCRIPTION) in my .mld, most of my index.mld start with slightly tweaked versions of $(DESCRIPTION) – I may try in the future to be more subtle about that but on the other hand since in index.mld the OCaml context is established there’s stuff like “this is an OCaml package” that would feel redundant.
I ended up having that little redudancy which you can witness for example in brr where the readme preamble is sligthly tweaked to this in brr’s index.mld with links in the docset. Having both README and index.mld here would just result in stuttering on the package page.
So I would rather suggest to have this (which is almost what odig has been doing for the past six years, I could tweak it to match it):
If there is an index.mld file, just use that. If not then use the opam description (which as a package publisher you can derive from your README, see above) followed with one section per library containing an automatically generated module index ({!modules:} directive) – ideally we would have a {!library-modules lib} directive but since that concept doesn’t exist in the toolchain we are left with hacks for now.
