| 17 Mar 2024 |
 kait | In reply to @fricklerhandwerk: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. indeed, the wiki is useful but I also find it goes into too much detail with flag setting. most of the time, if you set up things correctly, it should "just work". maybe I can add a section here in the meantime | 01:00:37 |
| kait | In reply to @fricklerhandwerk:matrix.org
Those were recently improved:
- https://github.com/NixOS/nixpkgs/pull/280592
- https://github.com/NixOS/nixpkgs/pull/277534
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. that is good to see! I was actually thinking about the writers that live under scripts.nix (confusingly named indeed). these let you write python and many other languages inline and are, afaict not in the manual at all | 01:02:20 |
| kait | there is an aged issue about it: https://github.com/NixOS/nixpkgs/issues/89759 | 01:03:11 |
| kait | there is documentation in the source, so maybe it's an issue of making them render in the manual? not sure | 01:06:41 |
 fricklerhandwerk | In reply to @rina/:matrix.org
there is documentation in the source, so maybe it's an issue of making them render in the manual? not sure Yeah it probably just needs to be wired up | 03:16:31 |
 @johannes.kirschbauer:scs.ems.host | In reply to @rina/:matrix.org
there is documentation in the source, so maybe it's an issue of making them render in the manual? not sure If you could give a concrete example i can tell you if its a wiring issue or would need to be maintained seperately anyways in the long term. I remembered that the writers because some of them are dynamically created by partial application | 15:44:08 |
| @johannes.kirschbauer:scs.ems.host | In reply to @rina/:matrix.org
there is documentation in the source, so maybe it's an issue of making them render in the manual? not sure * If you could give a concrete example i can tell you if its a wiring issue or would need to be maintained seperately anyways in the long term. I remembered that the writers because some of them are dynamically created by partial application and callPackages (plural s) | 15:44:33 |
| @johannes.kirschbauer:scs.ems.host | * If you could give a concrete example i can tell you if its a wiring issue or would need to be maintained seperately anyways. I remembered that the writers have some difficulties. Because some of them are dynamically created by partial application and mapped via callPackages (plural s). | 15:48:12 |
| @johannes.kirschbauer:scs.ems.host | Depends which methods we use for wiring them up. | 15:54:02 |
| @johannes.kirschbauer:scs.ems.host | I am also not sure when it was decided to move reference documentation out of the source it is related to. I think this is a mistake.
https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/trivial-builders/default.nix
We still have nixdoc to retrieve doc-comments and it was extended recently.
So wiring should only be a question of adding more files to the index. | 16:00:33 |
| @johannes.kirschbauer:scs.ems.host | Expanding it should be question of adding more include blocks like this:
https://github.com/NixOS/nixpkgs/blob/178fc9602881340bd8c02c0f9b64c25aedc0eb53/doc/doc-support/lib-function-docs.nix#L32C1-L39C34 | 16:01:45 |
| @johannes.kirschbauer:scs.ems.host | * I am also not sure when it was decided to move reference documentation out of the source it is related to. I think this was mistake.
https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/trivial-builders/default.nix
We still have nixdoc to retrieve doc-comments and it was extended recently.
So wiring should only be a question of adding more files to the index. | 16:02:14 |
| @johannes.kirschbauer:scs.ems.host | * I am also not sure when it was decided to move reference documentation out of the source it is related to. I think this was mistake.
I just took a look at this file: https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/trivial-builders/default.nix
It appears all doc-comments where removed from the code.
Regardless we still have nixdoc to retrieve doc-comments and it was extended recently.
So wiring should only be a question of adding more files to the index. | 16:04:32 |
 infinisil | Johannes Kirschbauer @hsjobeki: See https://github.com/NixOS/nixpkgs/pull/294944, I wouldn't call it being moved out of the source. Rather it was dedulicated in one place | 17:04:42 |
| infinisil | I'd also favor having it in the source code, but not having duplicated docs is more important than that | 17:05:27 |
| @johannes.kirschbauer:scs.ems.host | In reply to @infinisil:matrix.org
I'd also favor having it in the source code, but not having duplicated docs is more important than that I'd like moving those back into the source code until we have a working system that allows to track external documents, so we dont loose track of the reference documentation.
Maybe i'll open a PR soonish.
More importantly we should work on reference tracking for those that are moved already. | 18:39:15 |
