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 ?

In reply to @danielsidhion:nixos.dev
Arch has e.g. man.archlinux.org which they use a lot in their docs to link to manpages. I'm wondering if there's something similar for nixpkgs/nixos that I can use. Otherwise I'll just keep it without a link