 | Nix Documentation | 382 Members |
| This is the official channel for documentation in the Nix ecosystem. The documentation team meets here. More information: https://nixos.org/community/teams/documentation Video conference: https://jitsi.lassul.us/nix-documentation Meeting notes scratch pad: https://pad.lassul.us/p-Y8MjU2SdSD5qO1fnpCPA Past meeting notes: https://discourse.nixos.org/search?q=documentation%20team%20meeting%20order%3Alatest | 70 Servers |
| Sender | Message | Time |
|---|---|---|
| 1 Mar 2024 | ||
 Alyssa Ross | If the Nix flake is doing this, it should stop. | 19:20:17 |
| Alyssa Ross | ah, but it looks like it actually overrides stdenv in an overlay, so I guess that should work? | 19:21:10 |
| Alyssa Ross | It's very hard to read | 19:21:12 |
| Alyssa Ross | Ah, no, the overlay only applies the custom stdenv to Nix | 19:22:26 |
| Alyssa Ross | So it won't work | 19:22:28 |
| Alyssa Ross | cc Ericson2314 | 19:22:30 |
| Alyssa Ross | (It might not actually be ABI compatibility that's the problem — I just remember that it's definitely not expected for this to work) | 19:31:41 |
 John Ericson | Alyssa Ross: if you are using --gcc-toolchain as we are on Linux, isn't it supposed to be ABI compatible? | 21:27:53 |
| John Ericson | (more precisely, it is using at least parts of libstdc++ and friends so the ABI is the same?) | 21:28:49 |
| John Ericson | I don't fully get it but I always do clang development builds (mainly out of habit) and don't think I had a problem yet | 21:29:28 |
| Alyssa Ross | hmm, maybe it is? | 21:31:15 |
| Alyssa Ross | I'm not sure | 21:31:26 |
 @qyriad:matrix.org | clangStdenv links libgcc and libstdc++ on Linux, as is the default for Clang on Linux | 23:37:45 |
| Alyssa Ross | I definitely remember it being a problem before, but maybe it wasn't always this way. | 23:39:51 |
| 2 Mar 2024 | ||
 @delroth:delroth.net | hi there - what is the current "tech stack" recommendation for writing new documentation for currently undocumented projects in the Nix ecosystem? in this case, mostly internal facing (github.com/nixos/infra), if it changes anything | 03:23:33 |
| @delroth:delroth.net | (my ideal requirements: proper multipage support with navigation, markdown or at least not docbook, preferably a stylesheet that's not straight out of the 90s) | 03:25:40 |
| @delroth:delroth.net | (this sounds like something which should be documented, maybe with templates, btw :P but I didn't find anything after some quick research) | 03:26:31 |
 danielsidhion | In reply to @delroth:delroth.netThere is no recommendation 🥲 We have at least 3 different toolchains used throughout all our docs and want to find a way to reduce that amount (ideally to 1 toolchain), but afaik we haven't yet put the effort to see what things would fit our needs the best | 05:05:46 |
| danielsidhion | I literally got started on this exploration today. I want to make some internal nixpkgs docs (all the readme.md files) more visible, so I'm on a similar path as you | 05:07:55 |
 Qyriad joined the room. | 06:25:18 | |
| Qyriad | 06:27:35 | |
 fricklerhandwerk | delroth: Slightly more practically speaking (although generally my response would also be a deep sigh), if you only have prose and no or little structured data, I recommend to write things into markdown files and link them from the README. GitHub is the entry point for most of everything, and from that perspective it’s the most straightforward thing to do. If you do have mainly structured data, you’ll have to program it anyway, and in that case it basically doesn’t matter how you do it. It would be great though if you kept it simple relative to the minimal tech stack needed to contribute to Nix. I have my gripes with mdBook and Sphinx, because those are frameworks that assume certain things that usually don’t fit out use case all that much; and they are not really programmable to adapt them accordingly, and any attempt will make things very messy. nix-render-docs is a bit of a monster for backward-compatibility reasons, but actually a good example for how to do it well: it’s a purpose-built, highly structured Python program that transforms whatever there is to be documented about in Nixpkgs into a web page. | 11:10:37 |
| fricklerhandwerk | * delroth: Slightly more practically speaking (although generally my response would also be a deep sigh), if you only have prose and no or little structured data, I recommend to write things into markdown files and link them from the README. GitHub is the entry point for most of everything, and from that perspective it’s the most straightforward thing to do. If you do have mainly structured data, you’ll have to program it anyway, and in that case it basically doesn’t matter how you do it. It would be great though if you kept it simple relative to the minimal tech stack needed to contribute to Nix. I have my gripes with mdBook and Sphinx, because those are frameworks that assume certain things that usually don’t fit our use cases all that much; and they are not really programmable to adapt them accordingly, and any attempt will make things very messy. nix-render-docs is a bit of a monster for backward-compatibility reasons, but actually a good example for how to do it well: it’s a purpose-built, highly structured Python program that transforms whatever there is to be documented about in Nixpkgs into a web page. | 11:11:32 |
| fricklerhandwerk | * delroth: Slightly more practically speaking (although generally my response would also be a deep sigh), if you only have prose and no or little structured data, I recommend to write things into markdown files and link them from the README. GitHub is the entry point for most of everything, and from that perspective it’s the most straightforward thing to do. If you do have mainly structured data, you’ll have to program it anyway, and in that case it basically doesn’t matter how you do it. It would be great though if you kept it simple relative to the minimal tech stack needed to contribute to Nix. I have my gripes with mdBook and Sphinx, because those are frameworks that assume certain things that usually don’t fit our use cases all that well; and they are not really programmable to adapt them accordingly, and any attempt will make things very messy. nix-render-docs is a bit of a monster for backward-compatibility reasons, but actually a good example for how to do it well: it’s a purpose-built, highly structured Python program that transforms whatever there is to be documented about in Nixpkgs into a web page. | 11:11:53 |
| @delroth:delroth.net | In reply to @fricklerhandwerk:matrix.orgI wouldn't call markdown files in GitHub "proper multipage / navigation support" though :/ | 11:14:59 |
| @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.orgit 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 |