!avYyleMexqjFHoqrME:nixos.org

Nix Documentation

405 Members
Discussion about documentation improvements around the Nix ecosystem81 Servers

Load older messages


SenderMessageTime
18 Jan 2024
@mjolnir:nixos.orgNixOS Moderation Bot banned @bzzm3r:matrix.org@bzzm3r:matrix.org (<no reason supplied>).12:08:10
@philipp:xndr.de@philipp:xndr.deI all! I finally have time and energy for nixos stuff again. The thing I'm most interested in advancing RFC145 and providing documentation to previously undocumented functions outside of lib that are very relevant to many maintainers and that I personally also use outside of nixpkgs. I'm currently reading up all the discussions. It's a lot so if anybody can point me in a general direction of open tasks that aren't rejected in another thread or more generally what I could do to be helpful, I'd be very happy.16:58:35
@philipp:xndr.de@philipp:xndr.de I'd be happy to just work on PRs like this that document some functions if that would be helpful for example. 17:04:51
@danielsidhion:nixos.devdanielsidhion
In reply to @philipp:xndr.de
I all! I finally have time and energy for nixos stuff again. The thing I'm most interested in advancing RFC145 and providing documentation to previously undocumented functions outside of lib that are very relevant to many maintainers and that I personally also use outside of nixpkgs. I'm currently reading up all the discussions. It's a lot so if anybody can point me in a general direction of open tasks that aren't rejected in another thread or more generally what I could do to be helpful, I'd be very happy.
Hi! If you want to work on RFC145-related work, you should talk to Johannes Kirschbauer @hsjobeki I think.
To document undocumented stuff, I opened https://github.com/NixOS/nixpkgs/issues/276033 a while ago, but you can also scroll through this list of issues and see if you find anything that's applicable and interests you: https://github.com/NixOS/nixpkgs/issues?q=is%3Aopen+is%3Aissue+label%3A%229.needs%3A+documentation%22
17:38:18
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.host

Programming stuff where i could need help:

  • https://github.com/NixOS/nixpkgs/pull/262987
  • Extend the current python rendering: https://github.com/NixOS/nixpkgs/pull/281212
  • https://github.com/nix-community/nixdoc/pull/91

Documentation stuff:

  • Write: Just visit noogle.dev and pick a random function that is not documented. Place a doc-comment (see rfc145) at the position that noogle gives you. (Sometimes position tracking doesn't work yet, especially for functors.)
  • Extend the scope: danielsidhion: https://github.com/nix-community/noogle/pull/68. Once the CI finishes: https://noogle.dev/f/pkgs/appimageTools/wrapAppImage should display your wrapAppImage content. Unfortunately there is nothing documented ;)

Thanks. I am always looking to extend the scope of Noogle.

If we use the current toolset that i have as a benchmark. Given the 1.5k noogle discovered functions the answer currently is somewhat ~95%. Maybe we can get better, but we have to understand some more edge cases. A correct position tracking is Key to finding the doc-comments.

In the future this may become part of native nix, but thats a long way to go. And I currently focus on building incrementally better tools, until all questions are resolved and either I or somebody else volunteers to integrate that into nix natively.

19:04:22
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.host *

Hey, every piece of help is very valuable ;)

Programming stuff where i could need help:

  • https://github.com/NixOS/nixpkgs/pull/262987
  • Extend the current python rendering: https://github.com/NixOS/nixpkgs/pull/281212
  • https://github.com/nix-community/nixdoc/pull/91

Documentation stuff:

  • Write: Just visit noogle.dev and pick a random function that is not documented. Place a doc-comment (see rfc145) at the position that noogle gives you. (Sometimes position tracking doesn't work yet, especially for functors.)
  • Extend the scope: danielsidhion: https://github.com/nix-community/noogle/pull/68. Once the CI finishes: https://noogle.dev/f/pkgs/appimageTools/wrapAppImage should display your wrapAppImage content. Unfortunately there is nothing documented ;)

Thanks. I am always looking to extend the scope of Noogle.

If we use the current toolset that i have as a benchmark. Given the 1.5k noogle discovered functions the answer currently is somewhat ~95%. Maybe we can get better, but we have to understand some more edge cases. A correct position tracking is Key to finding the doc-comments.

In the future this may become part of native nix, but thats a long way to go. And I currently focus on building incrementally better tools, until all questions are resolved and either I or somebody else volunteers to integrate that into nix natively.

19:05:11
@infinisil:matrix.orginfinisilI'm afraid noogle won't have a long future if it's not integrated into the source it relies on..19:06:01
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.hostYes thats the dilemma. But rfc145 is the smallest common denominator. And i'd like to bring things closer together. 19:07:19
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.host * Yes thats the dilemma. But rfc145 is the smallest common denominator. And i'd like to bring things closer together in the future19:08:01
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.hostI'd like us to attach doc-comments to every user accessible function in nixpkgs. At least the important ones. But that might require a shift in the mental model, how we write documentation. Should I join the documentation team, and take some part of the ownership of the nixpkgs reference manual?19:13:02
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.host *

Hey, every piece of help is very valuable ;)

Programming stuff where i could need help:

  • https://github.com/NixOS/nixpkgs/pull/262987
  • Extend the current python rendering: https://github.com/NixOS/nixpkgs/pull/281212
  • https://github.com/nix-community/nixdoc/pull/91

Documentation stuff:

  • Write: Just visit noogle.dev and pick a random function that is not documented. Place a doc-comment (see rfc145) at the position that noogle gives you. (Sometimes position tracking doesn't work yet, especially for functors.)
  • Extend the scope: danielsidhion: https://github.com/nix-community/noogle/pull/68. Once the CI finishes: https://noogle.dev/f/pkgs/appimageTools/wrapAppImage should display your wrapAppImage content. Unfortunately there is nothing documented ;)

Thanks. I am always looking to extend the scope of Noogle.

If we use the current toolset that i have as a benchmark. Given the 1.6k noogle discovered functions the answer currently is somewhat ~95%. Maybe we can get better, but we have to understand some more edge cases. A correct position tracking is Key to finding the doc-comments.

In the future this may become part of native nix, but thats a long way to go. And I currently focus on building incrementally better tools, until all questions are resolved and either I or somebody else volunteers to integrate that into nix natively.

19:24:50
@danielsidhion:nixos.devdanielsidhionI'd love for us to document most stuff in the code directly and have it show up in the manual, but we'll have to figure out a lot of small details. Currently I'm working on the other end (adding/updating content to the manual and finding a good common structure for everything) and I have a wishlist of things I'd like to see in tooling that generates the docs19:25:38
@danielsidhion:nixos.devdanielsidhionIf you're interested in that, I can start a list so we can start figuring out work that needs to be done until we finally merge both efforts19:27:24
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.hostI'd really appreciate if we can work together. I also have some visions and ideas how stuff could work out nicely.19:28:24
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.host danielsidhion: I'd be interested if we could meet and present both our lists of stuff and maybe figure out a rough roadmap. (I'll have to prepare mine tho) 19:30:28
@danielsidhion:nixos.devdanielsidhionNeat, I like this idea. I'll ping you when I have my list (might take a few days, my availability will be reduced until next ~tuesday) and then we can chat once w19:31:23
@danielsidhion:nixos.devdanielsidhion * Neat, I like this idea. I'll ping you when I have my list (might take a few days, my availability will be reduced until next ~tuesday) and then we can chat once we're ready19:31:30
@philipp:xndr.de@philipp:xndr.deIf you want me to, I'll join. I should be able to get somewhat up to speed till then and will just document a few functions in the meantime.20:26:18
19 Jan 2024
@fricklerhandwerk:matrix.orgfricklerhandwerk I’d strongly support Johannes Kirschbauer @hsjobeki and danielsidhion taking ownership of Nixpkgs documentation! 00:09:58
@ThorHop:matrix.org@ThorHop:matrix.org changed their display name from hopland (meticulous montesquieu) to hopland (manners or stfu).05:12:15
@ThorHop:matrix.org@ThorHop:matrix.org changed their display name from hopland (manners or stfu) to hopland.05:14:40
@philipp:xndr.de@philipp:xndr.de I started to document wrapAppImage and I think I've found a few fault points that I'd like to discuss on Tuesday. 14:57:49
20 Jan 2024
@r_i_s:matrix.orgris_ joined the room.12:36:32
@r_i_s:matrix.orgris_https://github.com/NixOS/nixpkgs/pull/273840 hard to get people to review documentation PRs isn't it? ;) 12:37:07
@r_i_s:matrix.orgris_oh balls it has a merge conflict12:37:26
@r_i_s:matrix.orgris_just a sec12:37:31
@r_i_s:matrix.orgris_ok fixed12:42:52
@infinisil:matrix.orginfinisil ris_: Merged! 21:39:44
22 Jan 2024
@johannes.kirschbauer:scs.ems.host@johannes.kirschbauer:scs.ems.host danielsidhion: philipp I pm ed you, lets schedule our meet! Once we find a suitable schedule we'd announce it if anyone else wants to join. 11:41:25
@ThorHop:matrix.org@ThorHop:matrix.org changed their display name from hopland to IdeallyYes.15:06:13

Show newer messages


Back to Room ListRoom Version: 6