We have searches for packages and options.
the nixpkgs framework (it’s libraries and conventions don’t have a reference guides with any examples).
It seems that it was written in adhoc manner, although it’s devilishly brilliant, I know for a fact it’s devilishly brilliant, because devilishly brilliant programmers don’t write devilishly brilliant documentation.
Many things have a level of API documentation… nix has none, and grepping the source right into the weeds, is probably going to put people off on first use.
is a brave attempt , nix/OS doesn’t have shortage of documentation, it has a shortage of Library functions->real world example . I guess that’s somewhere between API documentation and a Cookbook.
take this an example.
let
sshkeys = pkgs.fetchFromGitHub {
owner = "abc";
repo = "def";
rev = "123";
sha512 = "456";
};
getpubkeys = user: builtins.readFile "${sshkeys}/${user}.pub";
mkuser = user: { name = user; isNormalUser = true; extraGroups = [ "wheel" ]; initialPassword = "hdsklf"; openssh.authorizedKeys.keys = [ (getpubkeys user) ]; };
in
{
users.users = (lib.genAttrs [ "alice" "bob" "charlie" ] mkuser) // {
dana = { name = "dana"; isNormalUser = true; extraGroups = [ "wheel" ]; openssh.authorizedKeys.keys = [
"ssh-rsa AAAA..."
]; };
};
}
that’s pretty amazing as it goes… but uses lib.genAttrs
which is completely undocumented. (or is it).
apart from…
it’s here… with examples…
so i think all this stuff is actually documented, it’s just tucked away in .nix files… it needs to be extracted and placed in a searchable system like nix options (which is brilliant).
It’s a massive task. By the time i first this post , another 10 functions will be added to nixpkgs standard library…
Most projects ‘win’ not because they are technologically superior, they just have superior documentation over other pieces of technology.