 | Nix Documentation | 422 Members |
| Discussion about documentation improvements around the Nix ecosystem | 87 Servers |
| Nix Documentation | 422 Members |
| Discussion about documentation improvements around the Nix ecosystem | 87 Servers |
| Sender | Message | Time |
|---|---|---|
| 28 Jun 2023 | ||
 sterni | I think the RFC should end up in a form where we enforce some kind of convention that means files are nixdoc-able and we can (optionally) also retrieve documentation at runtime in the repl (because it is convenient), but I'd sacrifize the latter if need be—it is a losing battle, since Nix has no module system-like semantics | 18:15:52 |
 fricklerhandwerk | sterni: which RFC do you mean? The one by Johannes Kirschbauer @hsjobeki or some hypothetical one that codifies nixdoc-like semantics? | 18:49:39 |
| sterni | the former | 18:50:09 |
| sterni | and with the current trajectory I think it could be the latter (although I'm a bit fuzzy on what is written down currently) | 18:50:30 |
 @johannes.kirschbauer:scs.ems.host | @sterni if i understand your concerns: yes treewalker would be slow (as slow as evaluation) but at least accurate. I guess you‘d suggest some limited set of patterns and nesting if you wanted static analysis solution. And as the RFC got critical mass of sheperds i am thrilled to make progress as soon as @lassulus schedules the first meetups. | 20:48:41 |
| @johannes.kirschbauer:scs.ems.host | Or just use the rfc outcome and build static analysis that can opt-in for dynamic evaluation in edge cases that are not possible with static analysis alone. | 20:52:56 |
 @pennae:matrix.eno.space | fwiw the renovated nixdoc (especially with our most recent pr) is a non-evaluating treewalker with a restricted set of allowed trees that are doc-able | 21:09:09 |
| @pennae:matrix.eno.space | it may be a bit too lax in what it accepts still | 21:09:19 |
| @johannes.kirschbauer:scs.ems.host | Yes the most recent PRs where really good. Especially #36 cleaned up a lot. And made good sense overall. The title is a little bit misleading as you did a lot of cleanup work there. However nixdoc is (currently) limited to analysing the AST. A real evaluator can track values and attach meta (e.g docs) inside the engine. Which results in much more reliable and generally applicable docs. But this is also way more slow because one need to run the evaluator. I think @sterni refers to a „treewalker“ as this thing that „walkes“ through the nested attributes dynamically. Imagine writing a nix function that collects all nested nixpkgs attributes path in a big list. (Funny slow thing but i know some including me, who tried) | 21:20:59 |
| @johannes.kirschbauer:scs.ems.host | * Yes the most recent PRs where really good. Especially #36 cleaned up a lot. And made good sense overall. The title is a little bit misleading as you did a lot of cleanup work there. However nixdoc is (currently) limited to analysing the AST. A real evaluator can track values and attach meta (e.g docs) inside the engine. Which results in much more reliable and generally applicable docs. But this is also way more slow because one need to run the evaluator. I think @sterni refers to a „treewalker“ as this thing that „walkes“ through the nested attributes dynamically. Imagine writing a nix function that collects all nested nixpkgs attributes path in a big list. (Funny slow thing but i know some including me, who tried) | 21:21:50 |
| @pennae:matrix.eno.space | yeah, that's what we would like to do too in the end. it needn't even be that expensive | 21:23:27 |
| @pennae:matrix.eno.space | until then walking the ast with minimal awareness of nix semantics is our best bet | 21:23:47 |
| @pennae:matrix.eno.space | In reply to @sternenseemann:systemli.orgas for that: the extension list in the manual is not entirely complete. there are a few more we haven't documented yet (most or even all of which predate the markdown tooling itself) | 21:26:54 |
| @pennae:matrix.eno.space | In reply to @sternenseemann:systemli.orgas for that: the extension list in the manual is not entirely complete. there are a few more we haven't documented yet (most or even all of which predate the markdown tooling itself) | 21:27:24 |
| sterni | Dynamically determining docs has a lot of problems: What constitutes the doc comment? The comment at the let binding? At the inherit exposing it? What happens if I pass the value through the identity function? etc. pp. This is because we don't have a sense of an exported symbol. Consequently we need to establish some sort of convention here that can be transferable to static doc generation since every file has to be a full Nix expression. When dynamically gathering documentation you don't suddenly have no issues: You need to know about the library's structure, e.g. which of the exposed functions are aliases? which functions are deprecated? Since you can't know this. The whole story becomes a lot worse if you are not dealing with anything as tame as When statically doing docs, you need to have a convention, yes, and need to somehow be able to tell it how it relates to the “library” as a whole. This also requires special knowledge about the library, but so does the dynamic solution. This is my point: Both solutions suffer from variations of the same problem; and the problem is that we have no module system, so a library could be structured in arbitrary ways and it is impossible to figure out what's what independently of the concrete code. | 21:34:53 |
| sterni | An important argument against dynamicism for me is that it'd be okay for <nixpkgs/lib>, but as soon as you have anything in pkgs proper that's to be documented you'll suffer | 21:35:50 |
| sterni | * An important argument against dynamicism for me is that it'd be okay for <nixpkgs/lib>, but as soon as you have anything in pkgs proper that's to be documented you'll suffer. | 21:35:56 |
| @pennae:matrix.eno.space | exactly, all of that. which is why we would need to develop very strong conventions for what is and isn't a doc comment, a documented item, etc before moving it into nix. whether it's ever moved is going to be up in the air regardless, and in the interim nixdoc-like solutions are kind of the only option anyway | 21:37:40 |
| @pennae:matrix.eno.space | and they do work well enough with some outside input for categorization and namespacing | 21:38:09 |
| @pennae:matrix.eno.space | if we converge on something that covers a sufficient number of cases we can start thinking about formalizing the rules applied at that point and putting them into nix, before that it's all just daydreams | 21:38:57 |
| sterni | that's also true the RFC has a big risk in the sense that it'll make whatever it prescribes eternal | 22:19:30 |
| @pennae:matrix.eno.space | codifying what is a doc comment and what isn't would be a welcome first step in any case, even if it ends there for a while. nixdoc has to hack around that not being well-defined quite a bit today to not pick up a lot of garbage as accidental doc comments :< | 22:21:16 |
| sterni | but nixpkgs & nixdoc could also do that provisionally | 22:23:10 |
| sterni | it's only a treewide commit away | 22:23:17 |
| @pennae:matrix.eno.space | we've had our share of treewide commits breaking new truths tbh xD | 22:24:03 |
| sterni | this is the way | 23:10:05 |
| @pennae:matrix.eno.space | if you want to have a go, please do! :) | 23:18:52 |
| @pennae:matrix.eno.space | hopefully nixdoc#40 makes it in soon so we can fully remove docbook from the nixpkgs manual, after that there's so much opportunity for improvement | 23:20:16 |
| 29 Jun 2023 | ||
 asymmetric | Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks. The little work I’ve done was reviewing nixdoc. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead. See you soon! | 13:08:58 |
| asymmetric | * Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks. The little work I’ve done was reviewing nixdoc PRs. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead. See you soon! | 14:12:44 |