| 16 Mar 2024 |
 infinisil | kait/: Agreed! Could you PR this? Source is https://github.com/NixOS/nixos-homepage/blob/main/src/content/teams/11_documentation.mdx | 03:42:14 |
 kait | sure! thanks for the link :) | 03:43:16 |
 ryantm | In reply to @infinisil:matrix.org
ryantm: Would be great if you could synchronise with the docs team a bit more regarding https://github.com/NixOS/nixpkgs/pull/108063, it looks like you want to merge it soon :) Mainly I'm trying to get it merged so others can easily try it out and try to do it in the most self contained way so it is low risk and can be ripped out easily. | 03:49:14 |
| infinisil | ryantm: I guess especially @pennae, who has been saying a lot that nixos-render-docs can already render with multiple pages with some small changes to the code. Furthermore Johannes Kirschbauer @hsjobeki and danielsidhion who have been investigating existing docs rendering tools to see if we could maybe not roll our own tooling at all. Your PR introduces yet another custom-built tool đ
| 03:53:55 |
| infinisil | I think we need a bit more convergence in docs tooling, so decreasing the different tools. We can still introduce new tools, but then we should also eventually deprecate another. I guess that's what your intending with your mmdoc, to replace nixos-render-docs | 03:55:53 |
| infinisil | That could be fine, but then we need to make sure that mmdoc supports everything that nixos-render-docs does and that somebody can maintain it. While nixos-render-docs is also pretty much maintained by just @pennae, it's written in Python, which at least from a superficial look is a lot more accessible than a C code base like your mmdoc đ
| 03:58:25 |
 danielsidhion | To add a bit to this - looks like one of the motivations is to introduce a fast docs building tool because the nixos html manual and manpages get built for nixos (depending on the nixos config). I haven't yet dug into why we need to build the html manual for the nixos config at all, but in any case, Johannes Kirschbauer @hsjobeki and I are looking to converge on less tooling mostly for the html part, and focused on the usual web docs experience, not the in-your-os docs experience. | 04:06:42 |
| infinisil | danielsidhion: html for nixos is needed so users can read the docs without needing an internet connection | 04:08:07 |
 @jade_:matrix.org | yeah i would suggest looking into optimizing nrd also? | 04:08:18 |
| @jade_:matrix.org | it feels like we are throwing several babies out with the bathwater here | 04:08:35 |
| danielsidhion | Depending on what we find (and this will mostly only matter after we finish looking at the options we have on our list), we might need a specific tool for manpage building anyway, and if that tool can do fast html for in-your-os, then that would be cool too | 04:08:50 |
| infinisil | Also nixos-render-docs is like really fast already.. a couple seconds | 04:09:09 |
| infinisil | * Also nixos-render-docs is like really fast already.. a couple seconds! | 04:09:11 |
| danielsidhion | A bunch of options we found that we're looking into say that they build manpages as well with plugins, but how good those things are is yet to be determined | 04:09:45 |
| @jade_:matrix.org | i still can't understand why everyone's immediate thought is constantly to replace nrd other than for lack of desire to look at the code and how it can achieve the goals set out | 04:09:52 |
| danielsidhion | I agree with the other arguments though - python is more approachable than c | 04:10:07 |
| @jade_:matrix.org | (for what it's worth i would be very suspicious of any man page generation plugin) | 04:10:08 |
| * infinisil agrees with giving nrd a fairer try. Having looked at the code base, it seems very approachable | 04:10:46 |
| @jade_:matrix.org | (generally man page generators (especially if they are bolted on the side of something else) are very very much trying to fit something that's not a man page into the shape of a man page and not considering the range of semantic expressiveness of the format) | 04:11:26 |
| danielsidhion | In reply to @jade_:matrix.org
i still can't understand why everyone's immediate thought is constantly to replace nrd other than for lack of desire to look at the code and how it can achieve the goals set out I've looked at the code already, and the effort to get it to where I'd like it to be is not insignificant | 04:11:42 |
| danielsidhion | Which is why I'm looking at other options too | 04:11:55 |
| kait | now for my main motivation for joining: what happened to the main manual? is there any announcement or documentation regarding the changes? | 04:25:16 |
| infinisil | kait/: Oh you mean because it looks different now? | 04:25:43 |
| kait | it does! | 04:25:50 |
| infinisil | kait/: That's a regression caused by the marketing team, see https://github.com/NixOS/nixos-homepage/issues/1251, unfortunately it was ignored.. | 04:27:04 |
| infinisil | danielsidhion here is the hero stepping in with a fix in https://github.com/NixOS/nixpkgs/pull/295847 đ | 04:28:09 |
| kait | oh gosh! | 04:28:51 |
| kait | so it is not permanent (relieved đ) | 04:29:14 |
| danielsidhion | (that PR is just waiting for approvals or more requests for changes btw!) | 04:29:23 |
| infinisil | kait/: Good rule in Nix in general: Things can be shitty for arbitrarily long, untli somebody decides to improve them | 04:30:53 |
