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

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.

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.

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.

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.

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

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

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