doc/lib-functions: remove warnings, add versions, cli

[ncfavier]

Building the nixpkgs manual currently triggers a bunch of deprecation warnings, because every attribute in lib is evaluated to see if it's an attrset to generate locations for.

Instead, share the lib subsets to include in the documentation between lib-function-docs and lib-function-locations so they can coordinate.

I also wanted to add modules (the upcoming lib.modules.typeCheck{,ing} might especially be worth documenting) but there are several obstacles:

• that file contains many functions that are too internal to be exposed in the docs. Maybe they should actually be made local, or split into a different file if we don't want to break the API?
• nixdoc generates documentation for non-toplevel local functions like collectStructuredModules (which then fail the build because they try to include location information that wasn't generated).

Fixes #116472

[fricklerhandwerk]

Looks good! Please implement @roberth's suggestions.

[ncfavier]

I struggled a bit with XML but here we go.

Note that the list of sections is ordered alphabetically now, which is probably better?

I also bumped the generate.section.toc.level so that we get TOCs for X.Y sections.

[fricklerhandwerk]

@ncfavier good point about the ordering, that indeed eluded me. I'm skeptical about changing the order haphazardly, as it (implicitly, but still) tells readers of the TOC something about relative importance and can be used to guide their attention.

Even if it's more cumbersome I'd prefer to instead pass the sections around as a list. @roberth what do you think?

[roberth]

it (implicitly, but still) tells readers of the TOC something about relative importance and can be used to guide their attention.

I don't think the ordering was particularly good, but I guess it works?

relative importance

Seems a bit fanciful for independent pieces of reference documentation.

---

Perhaps it may be helpful (for the TOC) to start the section names with lib.${name}, or just ${name}:

[fricklerhandwerk]

Seems a bit fanciful for independent pieces of reference documentation.

People will still tend to attempt reading it back to back in lack of other resources, so we may as well not be in the way of finding the most relevant things first.

[ncfavier]

Perhaps it may be helpful (for the TOC) to start the section names with lib.${name}, or just ${name}:

Done, but nixdoc escapes < to > so can't wrap it in <literal>.

[nixos-discourse]

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

https://discourse.nixos.org/t/tweag-nix-dev-update-42/24204/1