Over the past couple weeks I have made some major progress in documenting the Nixpkgs standard library functions. It is slow work, but thus far I’ve added web-facing documentation for over 25 functions. I’m working on roughly one each day. In addition to adding these to the public docs, each documented function has a link to where its source can be found on GitHub. I encourage you to check out my progress: Nixpkgs 23.11 manual | Nix & NixOS
However, this post is really more of a request for feedback. I found a fairly simple way to automatically test the docs too! It only took 50 lines of python to make a demo, and a bit over 100 lines to make a nice UX for the tool. Check it out over on my PR Verify doc examples by grahamc · Pull Request #48497 · NixOS/nixpkgs · GitHub
What do you think? Are these docs satisfying the need for a reference manual? Are these doc tests valuable?
I was just excitedly talking to my co-worker about your work on documenting the nixpkgs standard library. I like doc tests, because they also can serve as examples for how to use the functions. I usually search through the nixpkgs source for example usages; I expect having some in the manual will be more accessible.
About 3 years ago I first tried using NixOS and ultimately failed because I got lost in the documentation. Now trying NixOS about 6 months ago the situation has really changed and I’m hooked. I have to say thank you for emphasizing documentation!
This is a welcome addition. While these functions are already properly documented in source files, having a central point for this documentation will certainly be useful.
Maybe we can help with this, to speed up the process? After all, the library functions are mostly simple and easy to understand.
However, what I would like to see much more is documentation on pkgs functions. It can be really difficult to find out what they do, and how to properly use them!
Very cool! I’ve been hacking on a tool that I call nixdoc which can read the files in nixpkgs/lib and generate DocBook XML from them.
This already sort of works, but there are a few additional things that I’d like to add before looking into how to actually put it to use automatically.
Currently the doc comments contain significantly less information than what Graham has been writing manually, but I think it would be nice if the doc comments actually had that level of detail.
Check out this example for docs generated from strings.nix. If anybody wants to hack on this on the NixCon Hackday, ping me!
Edit: Progressing nicely, function arguments are now included, as are links to definition locations in the nixpkgs sources.
This made me think, is there a Nix repl available via an online evaluator in the style of Templates - Replit ? Having those examples with a link to play with them in an online evaluator, or inline, would be pretty nice for newcomers.
