In reply to @sternenseemann:systemli.org
do we have an overview of what markdown extensions/custom stuff you can use in the manual somewhere?

In reply to @sternenseemann:systemli.org
do we have an overview of what markdown extensions/custom stuff you can use in the manual somewhere?

Dynamically determining docs has a lot of problems: What constitutes the doc comment? The comment at the let binding? At the inherit exposing it? What happens if I pass the value through the identity function? etc. pp. This is because we don't have a sense of an exported symbol. Consequently we need to establish some sort of convention here that can be transferable to static doc generation since every file has to be a full Nix expression.

When dynamically gathering documentation you don't suddenly have no issues: You need to know about the library's structure, e.g. which of the exposed functions are aliases? which functions are deprecated? Since you can't know this. The whole story becomes a lot worse if you are not dealing with anything as tame as <nixpkgs/lib>. E.g. haskellPackages exposes some functions (callCabal2nix, …) that should be documented, but here treewalking becomes difficult, a lot of dynamicism is involved, you need to know what to ignore etc. (heck, the functions exposed could differ depending on platform or the like). In short, dynamically gathering docs is not a silver bullet.

When statically doing docs, you need to have a convention, yes, and need to somehow be able to tell it how it relates to the “library” as a whole. This also requires special knowledge about the library, but so does the dynamic solution.

This is my point: Both solutions suffer from variations of the same problem; and the problem is that we have no module system, so a library could be structured in arbitrary ways and it is impossible to figure out what's what independently of the concrete code.