generate nixpkgs neovim doc from the code

[teto]

I would like to upgrade the neovim wrapper documentation and I prefer to document it within the code, ie.: pkgs/applications/editors/neovim/wrapper.nix.
I've patched doc/doc-support/lib-function-docs.nix to get a better understanding of what was going on since the doc is scarce.

I ended up handcrafting the following neovim_locations.json:

{
  "neovim-unwrapped": "[pkgs/applications/editors/neovim/wrapper.nix:57](https://github.com/NixOS/nixpkgs/blob/master/lib/asserts.nix#L135) in `<nixpkgs>`"
}

and I copy/pasted some valid doc from somewhere else ( I convertedh the triple backticks into two to avoid messing up the preview):

/**
  Specialized `assertMsg` for checking if every one of `vals` is one of the elements
  of the list `xs`. Useful for checking lists of supported attributes.

  # Inputs

  `name`

  : The name of the variable the user entered `val` into, for inclusion in the error message

  `vals`

  : The list of values of what the user provided, to be compared against the values in `xs`

  `xs`

  : The list of valid values

  # Type

  ``
  assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
  ``

  # Examples
  :::{.example}
  ## `lib.asserts.assertEachOneOf` usage example

  ``nix
  let sslLibraries = [ "libressl" "bearssl" ];
  in assertEachOneOf "sslLibraries" sslLibraries [ "openssl" "bearssl" ]
  stderr> error: each element in sslLibraries must be one of [
  stderr>   "openssl"
  stderr>   "bearssl"
  stderr> ], but is: [
  stderr>   "libressl"
  stderr>   "bearssl"
  stderr> ]
  ``

  :::
*/
neovim-unwrapped: ##### THIS IS LINE 57

then I ran

nixdoc -c "toto" -d "lib.matt: this is description" -l neovim_locations.json -f "pkgs/applications/editors/neovim/wrapper.nix"

which outputs the disappointing

# lib.matt: this is description {#sec-functions-library-toto}

I am not sure how to proceed from there and even once that is fixed, I dont know how easy it would be to use this in nixpkgs ?

[teto]

@fricklerhandwerk if there was a single exemple in nixpkgs that shows how to generate doc from the code, I bet we would have a much much better (at least up to date) documentation. I want to update the neovim doc, we have plenty of new nice features but not having it tied to the code makes it just annoying enough.

[fricklerhandwerk]

Yeah nixdoc has become so vital now, but is itself still somewhat crude and underdocumented. @hsjobeki said he wanted to touch it once again to make it output structured data. Then we wouldn't have to create abominations such as mine, which you can use as an example.

Currently I can't spend any time on docs, but I take mental note that this is an issue with high leverage. Thanks @teto for prodding me.

[hsjobeki]

@fricklerhandwerk @teto
I would like to understand what you tried to document exactly.

A: Did you try to document a function ? (neovim-unwrapped: ...)
B: Did you try to document the pkgs.neovim-unwrapped package attribute?

From looking at your example documentation you just copied the from lib.asserts.assertEachOneOf which is a function.

But in the nix repl

nix-repl> pkgs.neovim-unwrapped  
«derivation /nix/store/n0aby5p7ig6z652isrb0wvpqp3x2kixl-neovim-unwrapped-0.10.2.drv»

So i am trying to understand what the documentable object is that you tried to describe.

Also the Command you are using here doesn't work like you expect. It scans for attribute identifiers. The location.json file is optional and not used as source.

cc @fricklerhandwerk we need to work on which objects relate to source code and are automatically retrievable

For example:

• functions
• attributes
• packages
• ...

Nixdoc has only (very opinionated) support for functions and attributes. But it also assumes that every attribute is a function.

[teto]

@hsjobeki thank you for following up. I am pretty excited about this.

A: Did you try to document a function ? (neovim-unwrapped: ...)

That's indeed my intention. I want to generate the documentation for wrapNeovimUnstable ( wrapNeovimUnstable = callPackage ../applications/editors/neovim/wrapper.nix { };)

Also the Command you are using here doesn't work like you expect. It scans for attribute identifiers. The location.json file is optional and not used as source.

Interesting. attribute identifiers as in x and y in { x = ..; y = ... } ?

I am rarely this clueless in face of a program but in case of nixdoc I confess I have no idea what's going on. Is there a verbose mode to try to understand what's going on ?

[hsjobeki]

Interesting. attribute identifiers as in x and y in { x = ..; y = ... } ?

Yes.

I am rarely this clueless in face of a program but in case of nixdoc I confess I have no idea what's going on. Is there a verbose mode to try to understand what's going on ?

No there is no verbose mode. Just diving into the code. But i wouldnt recommend it.

Nixdoc does not Support your use Case.
Noogle supports it.

https://noogle.dev/f/pkgs/wrapNeovimUnstable
(Your documentation would appear here)

I am in favor of formalizing some documentation exchange format. So we can just export the information from noogle. Instead of trying to extend and this incomplete and old tool.

It does its job well, which it was designed for. But this example is where the tool has reached its limits.