Package specifications in dune-project do not currently have an entry for documentation. This field is only available project-wide. I am not sure whether this is by design, but it certainly does not map neatly to OPAM files.

OPAM-files currently have a homepage and doc entry. The way I have been using these fields until now was to have homepage point to the github.io page of the project (not the repository) whereas the doc field was set to the API-documentation of that package.

I think it would help to clarify how documentation should be specified. Here is a suggestion on what might work well:

• Rename the project-wide documentation field doc to make it more obviously related to the OPAM field of the same name.
• Introduce a homepage field.
• If no project-widehomepage is provided, its default should be the source (e.g. GitHub) repository.
• If no project-wide doc field is provided, it should point to whatever homepage is.
• Each package in the project also has a homepage and doc field. If a package homepage is not provided, it should be the same as the project-wide homepage. If a package doc page is not provided, it should be the same as the project-wide doc page if it was explicitly specified. If the project-wide doc was inferred from the project-wide homepage and if a package homepage was provided, the package homepage should be used instead.

The advantage of the above approach is that most projects do not have to specify anything if their GitHub page contains all information, thus keeping project specifications clean and compact. But users can easily define these entries for the whole project and override them on a per-package basis as needed.