Great question, thank you for writing it out in detail!
First of all note that the example you linked declares a new NixOS module that does not exist anywhere else. There appears to be no usage examples of this module.
tl;dr: You will probably be able to make use of it by adding that file to the imports list in your NixOS configuration.
The NixOS Wiki on NixOS modules is a bit thin on explaining the difference between declaring options and defining configurations, and sadly it is often the only resource people manage to find. The authoritative source on NixOS modules is the (very unfortunately named) Writing NixOS Modules section in the NixOS manual.
Yes, and search.nixos.org/options (although the examples are usually per option).
There are two possibilities:
- The service or program you configure already has a NixOS module, which either shows how Nix attributes are mapped to the software’s settings or which has an attribute for custom settings as a string.
- There exists no NixOS module (as in your case) and you have to write your own, which can be a lot more involved (see NixOS Manual for instructions).
To check for existing configuration options, search.nixos.org/options is the best way.
Your input and help is highly appreciated, as expert Nix/Nixpkgs/NixOS users and contributors often don’t see the pain you’re going through (as theirs is in a distant past), and do not read the bulk of the documentation any more (because they don’t need to) to see why it may derail people.
Find here where and how you can contribute most easily, and check what the Nix documentation team is up to if you want to get in touch.