ocaml / ocaml/dune

[coqdoc] support for "--external"

Open
#7,912 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

rocq
Dominant language
OCaml
Stars
1.9k
Forks
500
Avg merge
15h 21m
Merged PRs (30d)
277

Description

When building Coq documentation, it would be pretty cool if the documentation of the project's dependencies could be linked automatically. An example of how such documentation is linked can be found here (taken from this Coq zulip message).

One possible idea is to automatically generate --external flags automatically for documentation. For example, if the theory you want to generate documentation for depends on stdpp, they you want to generate something like --external 'https://plv.mpi-sws.org/coqdoc/stdpp/' stdpp. This could be done by looking for the relevant URL in the stdpp opam file, which could be embedded as a specific metadata field that dune could produce in the opam files it constructs for theories with documentation.

CC @Alizter

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the linked Makefile example and the coqdoc --external behavior described in the issue. Then investigate how Dune constructs opam files and whether dependency documentation URLs can be represented as metadata. Done means defining and implementing a clear way to generate external links for documented dependencies.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
build-system, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.