I suppose I should take a look at what, if at all, the nixpkgs manual has for the module system.
I’m quite intimidated by this endeavor. Well, by the concept of working on it solo, that is. I don’t like solo-dev. I much prefer mob programming. I wish someone to join me in mobbing on this.
So, I have the module system chapter of the nixpkgs module open in an editor. And I read it. I suppose I should somehow identify missing parts in order to add them. But how? Go through the source code? I’ll try that.
So, for example, would it be progress if I manually added documentation for collectModules to the nixpkgs module system chapter? Now sure whom to tag, here. I’ll try not tagging, for now.
And, on the topic of auto-generating documentation… I feel frustration at the conflict between Nix being an expression-only language and the tremendous benefits of being able to generate documentation from source. Anyone who has experience with, for example, rustdoc, and also is involved in the Nix documentation effort is likely sad about this. I also realize that this isn’t the thread for this beyond expressing some frustration. But I do wish to say that I would like to get up to date on the latest thoughts regarding this problem, in case anyone cares to illumine me. Also, I’ll try to show up at the meetings, if you’ll have me.
1 Like
It is a potential solution, but we are stuck with the dynamic properties of the language and that it’s really hard to make changes to it without committing to something we might soon regret. The resources to do this are quite scattered and priorities of the people who should be involved are all over the place. I don’t expect this to make progress in a reasonable amount of time, but rather everyone slowly accreting insights why most things won’t work or scale. Until then we have to work around the language, as nixdoc does.
@roberth has a PR open with a top-down introduction to the module system: doc/module-system: Introduce concepts by roberth · Pull Request #240531 · NixOS/nixpkgs · GitHub
I‘m inclined to go bottom up and would propose approaching it from any of these two angles:
- Look at existing documentation and try to figure out where it’s not helpful or misleading and fix it in place. Don’t worry about infrastructure, just what’s immediately visible to readers.
- Go through the source code, try to understand it and document what’s missing or weird, and clean it up for readability if necessary. Don’t worry how it’s presented to the user, just what’s immediately accessible in the code. This has the potential for a deep thorny rabbit hole, therefore understanding what’s really going on first is crucial, which is why we’ll continue doing knowledge sharing with @roberth (and @infinisil when he’s back). But one can always start with clarifying source comments and bounce them against maintainers in PRs.
I am unsurprised at how closely those things are entangled.
- Automatic Documentation
- Module system
- Types (whatever that means
) - …
In my view, all are part of making Nix more modular, which is, in my opinion, an important step towards better architecture in nixpkgs and nix-related frameworks. (e.g fenix, dream2nix, floco, etc. )
Where we see those modular approaches already.
Whatever topic are you currently working on; In the end, you might find yourself contributing towards the “modular nix vision”.
Documentation → Important for Module descriptions; Interface-declaration, behavior, etc.
Module System → Implementation behind the modular Nix world; (I am still not convinced nixOS modules are the final approach because they potentially add much eval overhead)
Types → Some accepted format for abstract interface description; Maybe even adding some safety on top. (static and/or dynamic validation)
@blaggacao what do you think?
1 Like
That one’s private! It’s in a let binding and it’s only exposed as a deprecated attribute.
nix-repl> lib.modules.collectModules
trace: warning: External use of `lib.modules.collectModules` is deprecated. If your use case isn't covered by non-deprecated functions, we'd like to know more and perhaps support your use case well, instead of providing access to these low level functions. In this case please open an issue in https://github.com/nixos/nixpkgs/issues/.
«lambda @ /home/user/h/nixpkgs/lib/modules.nix:443:8»
In such a case, inline comments may make sense.
We could use a static module system, in the sense of most programming language module systems, or indeed haumea.
Such a framework would both provide dependency injection structure for writing a library, and it could provide a means to extract documentation, if that documentation is accessible to the language (as it is in e.g. python or the (dynamic) “NixOS” module system).
Let’s focus on the actual writing though. Instead of a docstring, we can have
# See doc/foo/bar.md#xyz
And that works perfectly fine, and has the benefit of easily distinguishing between user facing docs (.md files) and implementation docs (code comments).
4 Likes
Brainstorm. (Having Haumea in mind)
We could have, on a/b/c.nix a loader for a/b/c.md. We could then decide if we want to ship a default assembler into some doc framework (mdbook, et. al.).
1 Like