Indeed all references to that I am aware of talk about it at the “nixOS module system”, rather than “nix module system”.
This is where my confusion stems from.
I agree that coining a new term that finds its way into official glossaries and doesn’t imply dependency to NixOS would be a good thing.
Though “nix modules” might be sound to much as if there was some native support for them in nix itself, while “nixpkgs modules” again would feel weird, as nixpkgs itself doesn’t use them at all (but in fact provides them as part of its “stdlib”).
Would it make more sense that what was suggested that I contribute to is not whatever is behind the imports attribute and instead it is whatever abstracts NixOS modules? Or perhaps are these two parts of the same mechanism?
I’ve recently got involved with the docs team, and I think the module system is an area where I could be particularly helpful.
Indeed the goal would be to have good documentation for it as a standalone project independent of NixOS. (Although an occasional reference would be ok, these must not be required for understanding)
What documentation currently exists for the Nix module system
It’s split between
Nixpkgs manual (only since recently, very incomplete, just evalModules reference documentation)
NixOS (fairly NixOS focused, but some parts can be moved over without much editing)
Code and code comments. The manuals are arguably incomplete, and the code contains some user facing info.
The latter should of be mostly replaced by URLs and references to .md files.
What should remain of the docs in the NixOS manual is probably not a lot, because we want to move non-reference (and non-explanation?) docs out of the manual, into nix.dev.
I don’t think it’s an easy task to pick up, but if you have the time we can come up with a plan. I think it’d be crucial to work out the concepts and types first, so that the reference documentation will be consistent, and we’ll have a good foundation for further docs.
Thank you for summarizing. I have a few hours per day during this and the next two weeks. Then, Summer of Nix begins, which may decrease this to one hour a day for that duration. Possibly adding some more during weekends.
Does that sound alright? I’d love your help figuring out a plan, as much as you’d be willing to.
Alright. Discovering the Nix module system existing documentation. So, where is the repository?
One part of it seems like the options system, which seems to live here.
This seems to be currently documented in the source code. So I suppose that that’s the source of truth. So, ideally, we’d consume that truth and produce documentation. Auto-generated Nix documentation is not a new idea. I wonder what it would take to implement. And I wonder what progress has been made towards it.
The other part of the Nix module system seems to live here.
The same applies. Reference documentation could be generated from source. It should be, I suppose.
Since I’m not going to solve this problem in this context, I suppose we could see the source as reference documentation, instead of copy-pasting into some documentation. I don’t like duplication of truths. It carries high risk of de-sync between source and copy.
So, if I’m not to produce reference documentation, I should take a look at the higher level documentation.
Yes, as you say anything but reference should go to nix.dev. But we could also have a design document in Nixpkgs right next to the code and import it into the manual, to help readers navigate and understand the code.
Exporting doc comments sensibly probably requires a refactoring given how nixdoc currently works.
If I was to move, with appropriate modification (which I don’t know yet) Writing NixOS Modules from the NixOS manual to nix.dev, would the NixOS manual be worse off in any significant way? Would it lack something important about modules?
We should not just move around large chunks of documentation, but rather go very carefully and try to understand what’s wrong with a given piece and improve it incrementally in place. I recommend starting with obvious changes such as completing and structuring parameter listings. The scalable approach to that is documenting library functions in the code and collaborating with @pennae and @sternenseemann on figuring out how to sensibly develop nixdoc to make best use of in-code documentation.
What also works but takes more time to produce results is improving the conceptual introductions to get them right. While the module system is a generic mechanism, that chapter is highly specific to NixOS. We should instead start documenting the mechanism separately, for example on the Nixpkgs manual. Exposing the library there in more detail would be a good way to do that. I remember @roberth had a pull request in that direction.
The Nix Community’s module system is a type system with docstrings and a lattice value priority resolver *.
Form first principles, I found one paragraph of lattice theory e.g. from wikipedia extremely helpful.
I noticed that this is at the core of the module system when studying the cue-lang documentation.
* sort of every configuration management system is in better or worse ways. Nix Community’s solution is one of the better ones, which has been the trampoline in which nickel happened.
With regard to making the best use of in-code documentation, does anyone here feel that https://github.com/NixOS/rfcs/pull/145 is going towards being a solution for that?
