Dynamic list of mld pages for (documentation) stanza
Nobody has claimed this yet.
- 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 :
- include dune-docs.sexp into the dune file
- 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.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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