| 12 Jan 2024 |
 asymmetric | relatedly, i was looking into the pr splitting the nixpkgs manual up, which uses mmdoc, and i think it should probably be re-implemented using nrd? | 20:49:44 |
| asymmetric | mainly because, afaict, nrd is the sanctioned way forward | 20:50:34 |
 @jade_:matrix.org | this one, which claims to "complete autogenerated documentation for the whole nix-ecosystem" (which is fundamentally contradictory with all the other projects ostensibly doing this but having nothing to do with it): https://github.com/nix-community/docnix | 20:53:12 |
| @jade_:matrix.org | the description of this and how it fits into the way everything is going to fit together is very fundamentally confusing | 20:53:54 |
| @jade_:matrix.org | and i guess this is part of a meta thing of "we aren't tracking how all the new docs stuff is fitting together and what we actually want from a docs generation system that fulfils all requirements" | 20:55:01 |
| @jade_:matrix.org | (for the record i don't think that we are going to get away with having something that doesn't have very substantial amounts of our own code, in spite of what may have been said about that objective in the past re using sphinx or such. at the very least we will have to have a plugin or such) | 20:56:26 |
| @jade_:matrix.org | In reply to @asymmetric:matrix.dapp.org.uk
mainly because, afaict, nrd is the sanctioned way forward gosh we need to write these things down in a durable location that is not a github issue. we need a not-necessarily-wiki but easily modified, page that states that decision, and in general an overview of the tooling and its plans | 20:59:24 |
| @jade_:matrix.org | also, if we are closing the ryantm pr (why??), we should commit to that? | 20:59:43 |
| @jade_:matrix.org | * also, if we are closing the ryantm pr (why?), we should commit to that? | 21:00:16 |
| asymmetric | In reply to @jade_:matrix.org
also, if we are closing the ryantm pr (why?), we should commit to that? commit to what? | 21:01:33 |
| asymmetric | In reply to @jade_:matrix.org
gosh we need to write these things down in a durable location that is not a github issue. we need a not-necessarily-wiki but easily modified, page that states that decision, and in general an overview of the tooling and its plans yes, as is often the case, tribal knowledge is everywhere in the ecosystem. but i think in this case, what is used in nixpkgs is more or less what constitutes consensus, and at the moment, that's nrd (which was merged not even that long ago) | 21:05:07 |
| @jade_:matrix.org | In reply to @asymmetric:matrix.dapp.org.uk
commit to what? closing it. if it is not something we are doing | 21:09:09 |
| asymmetric | In reply to @jade_:matrix.org
gosh we need to write these things down in a durable location that is not a github issue. we need a not-necessarily-wiki but easily modified, page that states that decision, and in general an overview of the tooling and its plans i totally agree on a need to explain the tooling that produces the documentation for nix, nixpkgs and nixos, and to figure out how that tooling can deliver split nixpkgs manual, and ideally unified documentation building for all 3 projects | 21:09:28 |
| asymmetric | In reply to @jade_:matrix.org
gosh we need to write these things down in a durable location that is not a github issue. we need a not-necessarily-wiki but easily modified, page that states that decision, and in general an overview of the tooling and its plans * i totally agree on the need to explain the tooling that produces the documentation for nix, nixpkgs and nixos, and to figure out how that tooling can deliver split nixpkgs manual, and ideally unified documentation building for all 3 projects | 21:09:34 |
| @jade_:matrix.org | if we have a plan for a path forward, we should write it down. if we don't know the path forward we should describe what exists and its status | 21:10:01 |
| asymmetric | we should start with the latter. for the former, i think the only person atm who has deep familiarity with nrd is its author, pennae. Maybe Johannes Kirschbauer @hsjobeki, who has spent some time looking at it? | 21:10:51 |
| asymmetric | as to why nrd was chosen over mmdoc, iirc the main argument was that mmdoc being written in c was considered a liability (less people who can theoretically contribute, harder to change/extend without introducing subtle bugs, ...?) | 21:13:19 |
 raitobezarius | mmdoc was built in C with minimal closure concerns in mind | 21:14:50 |
| raitobezarius | nrd was built not in C with accessibility for newcomers in mind and ease of development (and probably more, I cannot speak for pennae) | 21:15:17 |
| raitobezarius | I know both codebases, I don't have deep familiarity with neither, but I can achieve deep familiarity with nrd in stupidly low amount of time | 21:17:01 |
| raitobezarius | It contains of course the hard work of pennae to find the edge cases and what not | 21:17:11 |
| raitobezarius | But beyond that, it's a fairly mundane program | 21:17:17 |
| asymmetric | In reply to @raitobezarius:matrix.org
I know both codebases, I don't have deep familiarity with neither, but I can achieve deep familiarity with nrd in stupidly low amount of time are you offering help? 🙃 | 21:17:51 |
| raitobezarius | No, but I can be there if there's any rescue-level tasks regarding nrd or this sort of stuff | 21:18:17 |
| raitobezarius | I think it's better if someone else grow experience with nrd :) | 21:18:27 |
| 13 Jan 2024 |
 @bzzm3r:matrix.org | How feasible are such "docs auto-generation" projects, given the lack of typing systems or other automated verification/compiler-based checks in Nix-the-language? | 00:32:30 |
 infinisil | At least nixdoc is used already for lib documentation. | 00:33:43 |
| infinisil | Tbh I gotta sleep though, good night! | 00:34:48 |
| @bzzm3r:matrix.org | Okay, and this is an important background RFC: https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md | 00:44:48 |
 @9999years:matrix.org | In reply to @infinisil:matrix.org
At least nixdoc is used already for lib documentation. is there a plan to use nixdoc to document .override arguments/defaults, package doc comments, or function arguments?
# In `my-func/default.nix`
{ }: # ← callPackage arguments
/* I want this to render as documentation for `pkgs.my-func`
*/
{
/* I want this to render as documentation for `myArgument`
*/
myArgument
}:
null
| 00:55:48 |
