| 8 Mar 2024 |
 @pennae:matrix.eno.space | like, the root problem with our docs isn't tooling support. switching out tooling again will only bind resources that could've been used for something that actually improves that status quo? | 08:08:54 |
 infinisil | In reply to @jade_:matrix.org
It seems borderline absurd to assume that there exists an off the shelf solution that actually has proper interactions with nix and consideration of anything that is not a web browser. Have you considered taking the nrd output and using it in your pipeline instead of trying to reinvent it, so we actually own the markup parser and such? Afaik there's nothing Nix-specific about nixos-render-docs at least | 09:45:49 |
| infinisil | In reply to @pennae:matrix.eno.space
like, the root problem with our docs isn't tooling support. switching out tooling again will only bind resources that could've been used for something that actually improves that status quo? I'd say it's a problem that we use different tooling for different projects. I guess it would make sense to try and see if nixos-render-docs could be used throughout though (such as for Nix and nix.dev). | 09:48:07 |
| @pennae:matrix.eno.space | not nix-specific, but nixpkgs/nixos-specific very much so. like manpage export, integration with the option system, crossreferencing, even performance optimizations needed to generate such huge documents as the nixos manual | 09:48:23 |
| @pennae:matrix.eno.space | In reply to @infinisil:matrix.org
I'd say it's a problem that we use different tooling for different projects. I guess it would make sense to try and see if nixos-render-docs could be used throughout though (such as for Nix and nix.dev). we did have that aspiration before we burned out on it all | 09:48:54 |
| infinisil | In reply to @pennae:matrix.eno.space
not nix-specific, but nixpkgs/nixos-specific very much so. like manpage export, integration with the option system, crossreferencing, even performance optimizations needed to generate such huge documents as the nixos manual Integration with the option system sounds very interesting, can you link to that? | 09:49:15 |
| infinisil | Oh I guess options.py | 09:49:23 |
| @pennae:matrix.eno.space | In reply to @infinisil:matrix.org
Oh I guess options.py correct | 09:50:04 |
| infinisil | https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py | 09:50:19 |
| infinisil | Oh so it renders it a bit differently on different targets | 09:50:31 |
| @pennae:matrix.eno.space | of course, that's why the manpage isn't terrible | 09:50:57 |
 @johannes.kirschbauer:scs.ems.host | But Is this website really what we'd like to give something to our users?
many off-the shelf rendering frameworks are really awesome (compare to our website), and they dont require us to maintain our own markdown parser and instead have more freedom because their community maintains the framework, while we can focus on writing documentation (and maybe add some plugins) | 10:08:02 |
| @johannes.kirschbauer:scs.ems.host | * But Is this website really what we'd like to give to our users?
many off-the shelf rendering frameworks are really awesome (compare to our website), and they dont require us to maintain our own markdown parser and instead have more freedom because their community maintains the framework, while we can focus on writing documentation (and maybe add some plugins) | 10:08:26 |
| @pennae:matrix.eno.space | have you considered: it took multiple years to do one migration, it has regressed, and it was only possible because we didn't use off-the-shelf components or we would've regressed even more. | 10:09:04 |
| @pennae:matrix.eno.space | do you really want to bind up another few years worth of work after the first migration hasn't even been shipping for six months | 10:09:27 |
| @pennae:matrix.eno.space | it's so far from "just drop in another framework", we're not sure you even understand what you're setting yourselves up for. | 10:10:18 |
 danielsidhion | My approach to looking into other frameworks is based on a simpler thought: we currently have 5k lines of custom code to render the manuals into what we see online. As far as I know, there is currently not a lot of flexibility in the tool to produce things in different ways, which means that if we want to change something, we'll need to go change the code. This is a big overhead that makes it hard to add improvements to the manuals. So I decided to look into other frameworks to see how much of our needs they can satisfy out of the box, and how much extra effort would be needed to satisfy the other needs. Because honestly, I actually find borderline absurd to assume that nobody out there has been able to solve some of the same problems we have into a tool that's more popular, has people to maintain it, and has a bigger ecosystem of documentation/plugins/knowledge to source from | 10:11:24 |
| @pennae:matrix.eno.space | most people out there are not multiple distros in a trench coat | 10:12:29 |
| danielsidhion | But our documentation doesn't have to follow suit | 10:13:54 |
| @pennae:matrix.eno.space | we can only stress again: make sure you're familiar with the problem domain before trying to Be Like The Others. | 10:14:32 |
| @pennae:matrix.eno.space | apart from that, we're not picky about nrd being replaced if there's something better. it's on you to find that thing though, and if you do, awesome! just consider the amount of effort it all takes to migrate again, the regression it will come with, and whether perhaps the tooling we have isn't fine enough if you just take a day to understand how it works | 10:15:45 |
| @pennae:matrix.eno.space | ¯\_(ツ)_/¯ your decision. | 10:16:14 |
| @johannes.kirschbauer:scs.ems.host | Maybe we could have a chat about this guys.
I feel like both parties have valid points and need to be taken seriously. | 10:16:27 |
| danielsidhion | I'd appreciate any links or resources you can send me that show things that we'll need to solve in the other docs frameworks as well. I have a list of things already, but idk how complete it is | 10:16:57 |
| @johannes.kirschbauer:scs.ems.host | In reply to @pennae:matrix.eno.space
do you really want to bind up another few years worth of work after the first migration hasn't even been shipping for six months As said, i feel like any potential migration needs to go through an RFC, to make sure all important aspects from the community taken into account | 10:19:08 |
| @pennae:matrix.eno.space | In reply to @danielsidhion:nixos.dev
I'd appreciate any links or resources you can send me that show things that we'll need to solve in the other docs frameworks as well. I have a list of things already, but idk how complete it is there's no full list as such in a single place, sadly. but whatever you'd choose would have to do manpage generation that isn't hot garbage (like the nix manpages), be able to run often and quickly (because docs is part of a nixos system build), support all the syntax extensions we have somehow (or rewrite a bunch of the docs), somehow be able to generate the option man/html pages, there's of course the issue of how to handle nixos module documentation chapter (which are distinct from option docs), the different formats of export for downstream consumers. there's more, those are just the few that immediately come to mind | 10:21:31 |
| danielsidhion | What do you mean by manpage generation? Are you referring to https://github.com/NixOS/nixpkgs/blob/master/doc/manpage-urls.json ? | 10:22:27 |
| danielsidhion | I didn't have performance on the list, but I'll add it as well | 10:23:06 |
| infinisil | danielsidhion: I think man configuration.nix is meant | 10:23:47 |
| infinisil | I don't think anything else is rendered with man pages | 10:24:17 |
