!avYyleMexqjFHoqrME:nixos.org

Nix Documentation

295 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 NixOS teams calendar: https://calendar.google.com/calendar/embed?src=b9o52fobqjak8oq8lfkhg3t0qg%40group.calendar.google.com&ctz=Europe%2FBerlin70 Servers

Load older messages


SenderMessageTime
2 Mar 2024
@delroth:delroth.netdelroth(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:nixos.devdanielsidhion
In reply to @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
There 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:nixos.devdanielsidhionI 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 you05:07:55
@qyriad:katesiria.orgQyriad joined the room.06:25:18
@qyriad:katesiria.orgQyriad 06:27:35
@fricklerhandwerk:matrix.orgfricklerhandwerk

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:matrix.orgfricklerhandwerk *

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:matrix.orgfricklerhandwerk *

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.netdelroth
In reply to @fricklerhandwerk:matrix.org

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.

I wouldn't call markdown files in GitHub "proper multipage / navigation support" though :/
11:14:59
@delroth:delroth.netdelroth 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.netdelroth 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:matrix.orgfricklerhandwerk

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@dooy:matrix.org left the room.11:27:55
@jade_:matrix.orgjade_
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
@redblueflame:matrix.orgredblueflame joined the room.18:25:44
@danielsidhion:nixos.devdanielsidhionmdBook 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:nixos.devdanielsidhionI'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 one19:54:06
@Minijackson:matrix.orgMinijackson danielsidhion: I've used Quarto for some of my doc, if you want yet another tool to explore 19:55:33
@danielsidhion:nixos.devdanielsidhionJust to confirm, you mean quarto.org right?19:57:06
@Minijackson:matrix.orgMinijacksonyes19:57:19
@Minijackson:matrix.orgMinijacksonhttps://epics-extensions.github.io/EPNix/ if you want an example19:57:53
@danielsidhion:nixos.devdanielsidhionTy19:58:10
@dmills27:matrix.orgDominic 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.orgjade_nope theres another new one20:13:43
@jade_:matrix.orgjade_after the rfc20:13:47
@jade_:matrix.orgjade_i think it is now under nix-community20:13:53
3 Mar 2024
@lurkki:pikaviestin.fiLurkkiclipboard.png
Download clipboard.png
14:03:53
@lurkki:pikaviestin.fiLurkkiHow can I render the docs into HTML locally?14:04:03
@lurkki:pikaviestin.fiLurkki
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:pikaviestin.fiLurkki* Ah, noticed the renderer is in a separate package14:12:13

There are no newer messages yet.


Back to Room ListRoom Version: 6