As I said in my review comments, this is looking really good, and if I had merge powers, I'd hit merge. But I also am not in touch with the details in a way that that infinisil or fricklerhandwerk might be, so it's a good thing I don't have merge powers.

Anyway I just want to say, as one new contributor to another, in case you do find it frustrating (not sure): please don't feel (too) frustrated by the fact that this is a process that will take time because both fricklerhandwerk and infinisil:

• are time constrained
• are careful, and therefore might have more requests for changes
• are human

I would suggest putting it up as a point for discussion in the meeting agenda for next week. It tends to get sorted out super fast in these meetings, because of the communication setup.

In the meantime I found it helpful to move onto other projects/PRs. I think of PRs as seeds that I plant...

In reply to @bzzm3r:matrix.org
How feasible are such "docs auto-generation" projects, given the lack of typing systems or other automated verification/compiler-based checks in Nix-the-language?

As the author of rfc145 and the creator of https://noogle.dev i can say:

It is very much feasible to autogenerate documentation from doc-comments. At least the API descriptions of all functions in nixpkgs.

Roughly 95% of what is in Noogle currently could also be autogenerated by any other tool.

I think one of the next important steps is to migrate to "doc-comments" (/** {commonmark} */)

asymmetric I've briefly looked into nrd (nixos-render-docs), and opened this issue: https://github.com/NixOS/nixpkgs/issues/280514
See the reply of @pennae there. I dont fully understand yet how to change nrd to clear the path. I'd super thankfull if someone from the community could do it. Otherwise... it will take me quite while, because i'm super busy recently with work related stuff.

In reply to @johannes.kirschbauer:scs.ems.host

As the author of rfc145 and the creator of https://noogle.dev i can say:

It is very much feasible to autogenerate documentation from doc-comments. At least the API descriptions of all functions in nixpkgs.

Roughly 95% of what is in Noogle currently could also be autogenerated by any other tool.

I think one of the next important steps is to migrate to "doc-comments" (/** {commonmark} */)

asymmetric I've briefly looked into nrd (nixos-render-docs), and opened this issue: https://github.com/NixOS/nixpkgs/issues/280514
See the reply of @pennae there. I dont fully understand yet how to change nrd to clear the path. I'd super thankfull if someone from the community could do it. Otherwise... it will take me quite while, because i'm super busy recently with work related stuff.

But who does the work to ensure that the doc comments match up with the actual code?

Also, it seems the doc comments RFC left defining function arguments as "future work"...

In reply to @johannes.kirschbauer:scs.ems.host

As the author of rfc145 and the creator of https://noogle.dev i can say:

It is very much feasible to autogenerate documentation from doc-comments. At least the API descriptions of all functions in nixpkgs.

Roughly 95% of what is in Noogle currently could also be autogenerated by any other tool.

I think one of the next important steps is to migrate to "doc-comments" (/** {commonmark} */)

asymmetric I've briefly looked into nrd (nixos-render-docs), and opened this issue: https://github.com/NixOS/nixpkgs/issues/280514
See the reply of @pennae there. I dont fully understand yet how to change nrd to clear the path. I'd super thankfull if someone from the community could do it. Otherwise... it will take me quite while, because i'm super busy recently with work related stuff.

But who does the work to ensure that the doc comments match up with the actual code?

Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

But who does the work to ensure that the doc comments match up with the actual code?

Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...wouldn't that also be necessary for stuff like noogle, or auto-gen docs?

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this is might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

In reply to @johannes.kirschbauer:scs.ems.host

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

In reply to @johannes.kirschbauer:scs.ems.host

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

bzm3r: You could also verify if your comments show up in noogle.

If you point noogle's "nixpkgs-master" flake input to your fork of nixpkgs and then execute nix build .#ui
You'll end up with the static site in ./result/lib/node_modules/noogle/out which you can serve statically with any http server. (e.g. nodePackages.http-server)

bzm3r: You could also verify if your comments show up in noogle.

If you point noogle's "nixpkgs-master" flake input to your fork of nixpkgs and then execute nix build .#ui
You'll end up with the static site in ./result/lib/node_modules/noogle/out which you can serve statically with any http server. (e.g. nodePackages.http-server)

Note: building takes quite a while the first time, because i modfiy c++ nix and the nix-build takes ~15minutes on my notebook)

In reply to @infinisil:matrix.org
No idea about the first, but the second one oh no..

In reply to @johannes.kirschbauer:scs.ems.host

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

Is there any tutorial how to develop on nixos-render-docs?
https://github.com/NixOS/nixpkgs/tree/528a4bb0ac5e5af73445472ec25945460add7768/doc#contributing-to-this-documentation
The only sentence there is:

The rendering tool is nixos-render-docs, sometimes abbreviated nrd.

I am not super familiar with the implied workflow python development on that package.

I'm Calling nix develop .#nixos-render-docs to load the build dependencies of the package in my shell.
But then executing pytest

Results in an error

....
    import nixos_render_docs as nrd
E   ModuleNotFoundError: No module named 'nixos_render_docs' 

Is there any tutorial how to develop on nixos-render-docs?
https://github.com/NixOS/nixpkgs/tree/528a4bb0ac5e5af73445472ec25945460add7768/doc#contributing-to-this-documentation
The only sentence there is:

The rendering tool is nixos-render-docs, sometimes abbreviated nrd.

I am not super familiar with the implied workflow python development on that package.

I'm Calling nix develop .#nixos-render-docs to load the build dependencies of the package in my shell.
But then executing pytest

Results in an error

ImportError while importing test module 'nixos-render-docs/src/tests/test_asciidoc.py'.
....
    import nixos_render_docs as nrd
E   ModuleNotFoundError: No module named 'nixos_render_docs' 

Is there any tutorial how to develop on nixos-render-docs?
https://github.com/NixOS/nixpkgs/tree/528a4bb0ac5e5af73445472ec25945460add7768/doc#contributing-to-this-documentation
The only sentence there is:

The rendering tool is nixos-render-docs, sometimes abbreviated nrd.

I am not super familiar with the implied workflow python development on that package.

I'm Calling nix develop .#nixos-render-docs to load the build dependencies of the package in my shell.
But then executing pytest

Results in an error

ImportError while importing test module 'nixos-render-docs/src/tests/test_asciidoc.py'.
....
    import nixos_render_docs as nrd
E   ModuleNotFoundError: No module named 'nixos_render_docs' 

Any ideas ?

In reply to @lennart:0520.ch
hej, I was Release Editor for 23.05 and 23.11; I guess it'd have some feedback to the editorial process; how do you all collaborate? are there meetings I could attend to give my thoughts? best lennart / riotbib on nixpkgs

In reply to @johannes.kirschbauer:scs.ems.host

Is there any tutorial how to develop on nixos-render-docs?
https://github.com/NixOS/nixpkgs/tree/528a4bb0ac5e5af73445472ec25945460add7768/doc#contributing-to-this-documentation
The only sentence there is:

The rendering tool is nixos-render-docs, sometimes abbreviated nrd.

I am not super familiar with the implied workflow python development on that package.

I'm Calling nix develop .#nixos-render-docs to load the build dependencies of the package in my shell.
But then executing pytest

Results in an error

ImportError while importing test module 'nixos-render-docs/src/tests/test_asciidoc.py'.
....
    import nixos_render_docs as nrd
E   ModuleNotFoundError: No module named 'nixos_render_docs' 

Any ideas ?