ocaml / ocaml/dune

Dynamic list of mld pages for (documentation) stanza

Open
#5,693 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Currently (documentation (mld_files ...)) does not support :include. It seems to be expected that the list of mld pages are static, which is fair.
But dynamic list of mld can make sense in some cases. Personally, i am a big fan of generating documenation from code, and sometimes ocaml mli are not the best format for the task, for instance

  • you can add to doc the list of REST endpoints of a server
  • you can generate documentation for a set of database tables described via some ocaml DSL
  • you can document some graph pipeline tasks built in ocaml dsl like ocaml-ci, or basically any embedded DSL.
    In those case, an easy way to do that is to generate mld pages to be embeded in ocaml docs. But if the list of things to document is only availbe in ocaml docs, either you cat everything in a single mld which can become really big real quick, or ideally you generate the list of mld via an executables.
    Currently i did not find any way to do that without big hack.
    For now, i hacked around this issue by :
  1. include dune-docs.sexp into the dune file
  2. have a rule in dune that generates a dummy file doc-rules by calling the executable to compute the list of pages to generate. It "hacks" a promote semantic, by writting directly to the git tree instead of build tree, and add (documentation) and (rule) stanza into it, but with dependency on the dummy doc-rules file.
  3. Then building doc kind of works with the included generated dune file.

To be honnest, i don't have suggestions on how to make thise clean, nor i think it is a big deal, but i was asked to open an issue for future reference

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 with the documentation stanza and its current :include handling, then inspect the dune file and generated dune-docs.sexp/doc-rules workaround described in the issue. Determine how mld page lists are collected and what existing documentation tests cover. Done means a supported way to derive the mld page list dynamically without the workaround.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.