| 2 Mar 2024 |
 @jade_:matrix.org | In reply to @fricklerhandwerk:matrix.org
Sphinx is used for nix.dev, but while I like it more than mdbook, it’s conceptually terrible on so many levels…
What’s wrong with GitHub? It generates a table of contents for every page and lists the directory tree, each in a side bar. It’s not great but works without having to do absolutely anything it has bad search and is not designed as a docs website, so you have a bunch of extraneous stuff around that's not relevant to the docs. their markdown renderer isn't bad but eh we can have nicer things than GitHub | 16:08:13 |
|  knownasred joined the room. | 18:25:44 |
 danielsidhion | mdBook was the first thing I explored yesterday and I have to agree that it assumes certain things that really don't help us, so if you're planning on using mdBook for the internal infra docs I'd say try not to spend too much time customising it. Things I have on my list to take a deeper look: mdBook, sphinx, unifiedjs (specially its rehype+remark stuff), docusaurus, vitepress, mkdocs. If you know of any other framework that might be good to take a look at, send it here or DM and I'll take a look at it too. | 19:51:18 |
| danielsidhion | I'll work enough with each one to get somthing up with the internal nixpkgs docs (the stuff in readme.md files) and some extra bits, and will host them somewhere later so people can see the results along with the written pros/cons I identify for each one | 19:54:06 |
 Minijackson | danielsidhion: I've used Quarto for some of my doc, if you want yet another tool to explore | 19:55:33 |
| danielsidhion | Just to confirm, you mean quarto.org right? | 19:57:06 |
| Minijackson | yes | 19:57:19 |
| Minijackson | https://epics-extensions.github.io/EPNix/ if you want an example | 19:57:53 |
| danielsidhion | Ty | 19:58:10 |
 Dominic Mills | In reply to @jade_:matrix.org
it has bad search and is not designed as a docs website, so you have a bunch of extraneous stuff around that's not relevant to the docs. their markdown renderer isn't bad but eh we can have nicer things than GitHub This actually might make a decent Google Season of Docs proposal 😃. I remember seeing this Summer of Code project for automating Puppeteer's docs (https://gist.github.com/tasneemkoushar/941128bc0d04f095fa01a5334617c65b) which incorporated search features using algolia. Nix doesn't have nice enough tooling to make this feasible, since to the best of my knowledge, the only thing we have to automating the generation of docs is nixdoc (https://github.com/nix-community/nixdoc) which is nice but leaves a lot to be desired. | 20:13:22 |
| @jade_:matrix.org | nope theres another new one | 20:13:43 |
| @jade_:matrix.org | after the rfc | 20:13:47 |
| @jade_:matrix.org | i think it is now under nix-community | 20:13:53 |
| 3 Mar 2024 |
 Lurkki | 
Download clipboard.png | 14:03:53 |
| Lurkki | How can I render the docs into HTML locally? | 14:04:03 |
| Lurkki | In reply to @lurkki:pikaviestin.fi
How can I render the docs into HTML locally? Ah, noticed it's in a separate package | 14:11:56 |
| Lurkki | * Ah, noticed the renderer is in a separate package | 14:12:13 |
| 5 Mar 2024 |
| danielsidhion | Conflicted about something: in its current state, snapTools.makeSnap produces broken snaps. With a patch, it works only for static binaries, but I haven't figured out a way to make it work in more general cases, and the spec leads me to believe that making it work will be very hard. Do I put in the nixpkgs manual that makeSnap is broken as-is, but still document the function normally? Do I just remove it from the manual entirely and proceed with removing the code for makeSnap? Looks like it's been broken since late 2020 according to this issue: https://github.com/NixOS/nixpkgs/issues/100618 | 01:42:12 |
