 | Nix Documentation | 415 Members |
| Discussion about documentation improvements around the Nix ecosystem | 84 Servers |
| Nix Documentation | 415 Members |
| Discussion about documentation improvements around the Nix ecosystem | 84 Servers |
| Sender | Message | Time |
|---|---|---|
| 16 Mar 2024 | ||
 fricklerhandwerk | In reply to @rina/:matrix.org There is a wealth of information here: https://nixos.wiki/wiki/C Mostly written by @Mic92 in past years AFAIK. Would be great to have that closer to the code, because all of that is Nixpkgs material. We still haven't really figured out how to organise troubleshooting tips and other guide-like material across the ecosystem though. The last state of affairs was that we converged on the idea that it should be a bit like what Johannes Kirschbauer @hsjobeki proposes for function documentation, but for guides: have a uniform format used across Nix, Nixpkgs, and NixOS, and present that in one place, annotated with tags and searchable. But that is a lot of "should", and will require thinking about the structure of the manuals, and moving around lots of text. | 15:27:15 |
| fricklerhandwerk | In reply to @rina/:matrix.org Those were recently improved:
But there's definitely still work to do. Ideally we'd also render that stuff directly from the source. At least there is no duplication any more. I can imagine danielsidhion could help with reviews. | 15:31:48 |
| fricklerhandwerk | In reply to @rina/:matrix.org* There is a wealth of information here: https://nixos.wiki/wiki/C Mostly written by @Mic92 in past years AFAIK. Would be great to have that closer to the code, because all of that is Nixpkgs material. We still haven't really figured out how to organise troubleshooting tips and other guide-like material across the ecosystem though. The last state of affairs was that we converged on the idea that it should be a bit like what Johannes Kirschbauer @hsjobeki proposes for function documentation, but for guides: have a uniform format used across Nix, Nixpkgs, and NixOS, and present that in one place, annotated with tags and searchable. But that is a lot of "should", and will require thinking about the structure of the manuals, moving around lots of text, and building automation for presenting the result. | 15:32:40 |
 @johannes.kirschbauer:scs.ems.host | Since #280592 The documentation is not closely connected to the source anymore. The doc-comment was replaced by an explicit markdown document. Which is fine but we should have a more distinct way of creating a reference to the document such that a doc-comment tool knows that the documentation exists but is located at a different place. We actually will need some more of those „rediretcion-directives“. One task is to research if there are usable standards for that (i some how doubt that) or to come up with a good solution on our own. | 16:19:51 |
| @johannes.kirschbauer:scs.ems.host | * Since #280592 The documentation of ‚writeShellApplication’ is not closely connected to the source anymore. The doc-comment was replaced by an explicit markdown document. Which is fine but we should have a more distinct way of creating a reference to the document such that a doc-comment tool knows that the documentation exists but is located at a different place. We actually will need some more of those „rediretcion-directives“. One task is to research if there are usable standards for that (i some how doubt that) or to come up with a good solution on our own. | 16:20:22 |
| @johannes.kirschbauer:scs.ems.host | * Since #280592 The documentation of ‚writeShellApplication’ is not closely connected to the source anymore. The doc-comment was replaced by an explicit markdown document. Which is fine but we should have a more distinct way of creating a reference to the document such that a doc-comment tool knows that the documentation exists but is located at a different place. We actually will need some more of those „rediretcion-directives“. One task is to research if there are usable standards for that (i somehow doubt that) or to come up with a good solution on our own. | 16:20:56 |
 danielsidhion | I can help review anything related to nixpkgs manual. Prepending "doc:" to the PR title is the easiest way to get my attention (I keep track of every PR that follows this), but pinging me or requesting review directly from me also does the job | 16:59:26 |
| fricklerhandwerk | In reply to @johannes.kirschbauer:scs.ems.hostWith nixdoc taking shape, does anything speak against systematically moving that text into the code? | 17:18:28 |
| @johannes.kirschbauer:scs.ems.host | It would still be nice for longer documents like those for stdenv & mkDerivation. | 17:20:40 |
| danielsidhion | In reply to @fricklerhandwerk:matrix.orgThere are a few tricky cases that we'll need to handle that requires more thought before doing it right away (one that we already encountered is function with doc-comment that documents inputs, but then more doc-comments on each function argument) | 17:21:19 |
| danielsidhion | Those cases (and what we're doing with them) aren't documented right now, and the way we handle these will likely change in the future, which is why we're being a bit conservative with the move | 17:23:02 |
 @pennae:matrix.eno.space | oh wow we only now get to see the backlog. someone asked about multipage rendering in nrd it seems? html:into-file makes that happen, the manual already uses that to render the option docs and appendix. isn't automated per chapter/part, but could be added easily (the infra to do this is there already) | 18:13:51 |
| @pennae:matrix.eno.space | getting the official manual to render multipage is literally just sprinkling html:into-file directives on the includes and letting it build | 18:14:46 |
| @pennae:matrix.eno.space | (which, we do want to stress at the risk of offending someone, we have said at least five different times, including in meetings of the docs team) | 18:15:58 |