The thing with #NixOS that annoys me the most: Installation is easy, but then you sit there on a command line and there are no examples on how to progress, I don't want to read non-descript configs of other people linked in a boring long list from the wiki. And no I don't want to watch a Video guide of someone talking me through a text-configuration-file. Documentation is helpful for describing how Nix and the config works. What's missing? Something like: "Here is an example running KDE Plasma"
Do you know of search.nixos.org? My procedure for determining how to make some change to my configuration is to go there, find some related option, and look at the documentation of the module this option is in. In more complicated situations (e.g. audio configuration, where there are multiple things that expose the same interface towards applications) I have to go search the nixos wiki and until now that always sufficed.
@robryk How do i find the documentation for a search result on the search site? It seems the UX is a bit lacking here, discoverability seems not very high (or I am just blind). I explicitly do not want to read the nix source files here as i am not familiar enough with the syntax to get clear information from that.
I generally go to the source file and:
- look for other options defined in the same file and their description strings,
- look around for the xml file that contains the module's documentation,
- actually look at implementation if these two fail (which often doesn't really require much comprehension of the language, because often what you want to see is what gets interpolated into the same config file).
@robryk yeah that's absolutely fine for advanced users. And I am doing exactly that but it is in no way easy to understand.
Would cross-linking to documentation of similar options/the docbook for the appropriate module from search.nixos.org be significantly helpful?
Do you mean documentation for packages or for nixos modules/config options, or both?
@robryk three things really: the pkg build scripts sometimes have parameters to recompile a "extra special" version that does not come from a binary cache, then the package itself should tell me when i have to rely on "dumping stuff into a config file" and when i probably should use an exported configuration. I don't have a solution for that, and I am to unexperienced with nix to really tell anyone "How it should be done"
Re arguments to the package to modify it: fully agreed, they are documented something between badly and not at all.
I don't understand what configuration files you are referring to in the other two cases.
@robryk For example you can configure many services directly with nix expressions but often you have something like "extraArgs" or "text" where you can dump super special stuff that gets appended to the produced configfile or even overrides it completely. (Example in Screenshot)
Ah, you mean in nixos modules as opposed to in packages.
Yes, that part is very rarely well documented. My rule of thumb is that, unless extraRawTextConcif is the only way some service has of being configured, I should not use it without reading the implementation of the module :(
@robryk hm perhaps, i am not sure as the documentation i could find was extremely fragmented. The more users contribute packages the more complex it will be to have consistent and discoverable documentation. It's a hard problem and the arch wiki was not created in a day either and their userbase is much bigger and even that does not contain everything or is particularly well organized, the problem is perhaps a bit of bias too (i know my way around arch pretty well) and nixos is so much different