In reply to @mightyiam:matrix.org
Sorry, there's no documentation. There are tests for the repl examples and there are tests for the WIP expression examples.
https://github.com/mobusoperandi/eelco/tree/0eb9042220befe188aa4399ffc6615579cebdd5f/crates/eelco/tests

In reply to @mightyiam:matrix.org
Sorry, there's no documentation. There are tests for the repl examples and there are tests for the WIP expression examples.
https://github.com/mobusoperandi/eelco/tree/0eb9042220befe188aa4399ffc6615579cebdd5f/crates/eelco/tests

How does a user specify input, precisely? If I look for example at the Rust doctests page, there's a fair bit there about syntax. There's also the additional constraint that these things exist in doc strings. We don't really/necessarily have docstrings here, so how do I present a list of assertions for a nix repl to check?

What kind of output does does a doc tester produce (is it just a pass/fail, is there a way to extract the LHS and RHS of the input assertions)? Would you find it useful to co-opt the language/structure in the issue linked above, or does it pose unnecessary constraints on your work?

In reply to @mightyiam:matrix.org
I lost you at "input". What's input, please?

In reply to @mightyiam:matrix.org
I lost you at "input". What's input, please?

How does a user specify input, precisely? If I look for example at the Rust doctests page, there's a fair bit there about syntax. There's also the additional constraint that these things exist in doc strings. We don't really/necessarily have docstrings here, so how do I present to the program what is essentially a list of assertions for a nix repl to check?

What kind of output does does a doc tester produce (is it just a pass/fail, is there a way to extract the LHS and RHS of the input assertions)? Would you find it useful to co-opt the language/structure in the issue linked above, or does it pose unnecessary constraints on your work?

In reply to @mightyiam:matrix.org
We're working on this in mob format regularly. Wanna join?

In reply to @bzzm3r:matrix.org

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

Low-tech is a really bad term to describe what I mean, sorry. It’s really about three things:

1. Lean towards manipulating data rather than code that does things (cf. "show me your tables“, declarative programming)
2. Minimize length of processing chain and number of indirections (less stuff to understand)
3. Prefer widespread, well-understood tools, even if they’re somewhat wrong (less new stuff to learn)

And of course it’s a trade-off between amount of ongoing manual work and threshold to contribute. Because the system is so large and the number of people with deep knowledge so small, I’m inclined to lower the threshold and hope to attract more talent with a gentle learning curve. The more people care, the more will eventually run into the hard problems, the more may have the right combination of time, skill, and motivation to finally solve them.

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.

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.

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.