Section headings from comments at top of files

[tazjin]

Currently sections (i.e. the "groups" of functions, strings, lists etc.) generated by nixdoc don't have any descriptions other than what the user specifies on the CLI.

Some files (for example lib/debug.nix) have multi-line comments at the beginning that could be interpreted as section headings.

Implementation wise, the rnix parser will probably attach those as meta to the very first AST node which should be relatively easy to check for.

[nixos-discourse]

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

https://discourse.nixos.org/t/how-to-generate-documentation-from-arbitrary-nix-code/22292/8

[fricklerhandwerk]

@zmitchell is interested to pick this up

[tazjin]

Note that before adding any complex features like this depending on parser output, the parser should be upgraded. nixdoc is using a very old version of rnix, and the API has nothing to do with the current one anymore - the longer that isn't done, the harder it will be eventually if more things are built on the old API.

[zmitchell]

Right, is that what's happening here? https://github.com/nix-community/nixdoc/pull/36

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-04-06-documentation-team-meeting-notes-39/27048/1

[phaer]

I ran to this and pushed a quick implementation to https://github.com/nix-community/nixdoc/pull/70 . It's naive w.r.t to white-space handling and passes the string on without parsing or so, so once currently looses the section headings. On the plus side it's a trivial implementation.

[infinisil]

This is now implemented with #70!