| 2 Mar 2024 |
 @delroth:delroth.net | I might just try to figure out how to wrangle mdbook into generating a not-completely-terrible looking output, that way at least we're not too far from the tech stack of a few other projects | 11:16:00 |
| @delroth:delroth.net | Usually outside of Nix* my first choice would be sphinx but there's basically zero usage of it in the Nix* ecosystem and I don't want to be the guy that adds yet another stack to the list | 11:16:59 |
 fricklerhandwerk | 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 | 11:20:11 |
|  @dooy:matrix.org left the room. | 11:27:55 |
 @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 |
 infinisil | danielsidhion: I'd be in favor of removing, or rather replacing with an error saying why it was removed. That error could also link to that issue | 03:01:18 |
 Philip Taron (UTC-8) | Is there an existing issue or proposal for making :doc (from nix repl) work on more than just builtins? | 18:35:23 |
| @jade_:matrix.org | In reply to @philiptaron:matrix.org
Is there an existing issue or proposal for making :doc (from nix repl) work on more than just builtins? hahahaha lmao | 18:47:27 |
| @jade_:matrix.org | (this is why the nix-doc plugin was created in 2021) | 18:47:40 |
| Philip Taron (UTC-8) | How much ugly history is there? | 18:48:11 |
| @jade_:matrix.org | https://github.com/NixOS/nix/issues/3904 | 18:48:29 |
| @jade_:matrix.org |
I will say, my implementation cannot die to the bikeshed because it cannot in good conscience ever be merged ;-)
| 18:49:02 |
| @jade_:matrix.org | (and indeed it has been working perfectly for the past three and a half years) | 18:49:38 |
