| 12 Jan 2024 |
 Chris McDonough | (i'd like to make more changes to it that are related to function argument styles) | 17:25:15 |
| Chris McDonough | (but that are not related to writeText* funcs) | 17:25:46 |
 danielsidhion | I'm reviewing the pr right now | 17:33:26 |
 @jade_:matrix.org | In reply to @asymmetric:matrix.dapp.org.uk
i think we would really benefit from this. it would make it easier for people to contribute across the different projects on the platform, create links when appropriate, etc etc there's a bunch of efforts of unclear relation involving writing new docs builders. we really need to write down what they are and probably make a tracking issue to try to not step on our own toes. | 18:20:29 |
 infinisil | danielsidhion: Manual is now being updated again! https://nixos.org/manual/nixpkgs/unstable/ | 19:40:43 |
| infinisil | (merged the PR and manually triggered an update) | 19:40:56 |
| danielsidhion | Thank you for fixing it! | 19:41:26 |
| danielsidhion | In reply to @jade_:matrix.org
there's a bunch of efforts of unclear relation involving writing new docs builders. we really need to write down what they are and probably make a tracking issue to try to not step on our own toes. I think that's important, added this to the agenda for next meeting so it's not forgotten to be at least discussed, hopefully the issue is created during the meeting though | 19:43:53 |
 asymmetric | jade_: what projects/efforts are you thinking of? i know of nixos-render-docs (which is actually used in nixpkgs/nixos), mmdoc (which was supposed to be used, but isnt'). anything else? | 20:40:07 |
| 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 |
