Generate documentation for language specific libraries in nixpkgs manual

[sternenseemann]

Some ecosystems in nixpkgs have their own specific library with a set of helper functions. Ones that I know of are coqPackages and haskellPackages. It would be nice if we could have their documentation generated and added to the nixpkgs manual as well.

As far as I can see it the following items would be required to make this possible:

• Patch nixdoc to allow specifying the prefix in an alternative way: Instead of lib.${category}, we'd need to be able to specify haskell.lib or coqPackages.lib
• Allow alternative lib source locations in doc/doc-support/lib-function-docs.nix
• Make doc/doc-support/lib-function-locations.nix understand the alternative locations
• Decide where to include the documentation — in the language specific section would be nice, but this does not seem to be possible easily since our markdown based setup for those sections doesn't allow inclusions of sub sections (?!). Alternatively we can use the default lib section where lib.* is documented currently.

cc @tazjin (nixdoc) @ryantm (mmdoc) @NixOS/haskell @CohenCyril (Coq extra-lib)

[ryantm]

We are pretty close to removing Docbook from the Nixpkgs manual.

1. We need to convert attrsets and asserts sections to be automatically generated (I'm currently working on this)
2. We need to update nixdoc to output Markdown
3. We need to choose a Markdown renderer and use it. Hoping to use mmdoc here, since I've been developing it for the NixOS manual and I think it is at least acceptable right now.

The point about not being able to include sections will probably be moot when we make these changes. In mmdoc, there isn't any section nesting, you just change the order of links in the table of contents to control the order sections appear in the manual. So for example, we can have all the generated docs in one place, but have them show up as under their respective manual sections.

Last I remember, the Haskell Docs were on a completely separate website anyway. (Hopefully they can be reintegrated later.)

[sternenseemann]

Last I remember, the Haskell Docs were on a completely separate website anyway. (Hopefully they can be reintegrated later.)

Currently working on porting them back which is when this came up :)

[CohenCyril]

FTR coq extra-lib is general purpose and I mean it to be fully integrated into the general lib.
See #113661 where the extra-lib file disappears completely, so I prefer working towards integration rather than a specific means to generate the documentation.

CC @Zimmi48 @vbgl

[sternenseemann]

Right, I remember. Since haskell.lib is mostly helpers for overriding the haskell package set, this approach makes less sense for us, but for Coq this seems a sensible way forward.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-10-22-documentation-team-meeting-notes-12-nixcon-edition/22689/1

[teto]

the lua doc is out of date and it would be easier if I could update the doc right next to the code as is done for lib/. I tried nixdoc on a private nix project but I was not able to generate any output. Pinging the doc master @fricklerhandwerk and thanks for your work btw, you are the most influental man on the nix experience at the moment, at least for newcomers.no pressure ;)

[fricklerhandwerk]

@teto thanks, no pressure perceived. 😉 I suppose that would be a good topic for an office hour. I recently dabbled with nixdoc, I should be able to show you around.