nix-doc

nix-doc 是一个利用 rnix Nix 解析器的 Nix 开发者工具，用于智能文档搜索和标签生成。

功能

• Nix 插件，添加了一个内置函数，可以以友好的格式显示 lambda 对象的签名和文档
• 命令行工具，在目录中搜索 Nix 文件中的函数，并显示匹配项的文档
• 类似于 ctags 的标签生成器，可以生成与 Nix 源代码兼容的 vim 标签文件
• Rust 的高性能、多线程实现

设置

# nix-doc is in nixpkgs
$ nix-env -i nix-doc

# you can alternatively get it from git
$ nix-env -i -f https://github.com/lf-/nix-doc/archive/main.tar.gz

# or if you don't want to use nix (only includes the command line tool for
# search and tags)
$ cargo install --locked nix-doc

Nix 插件

要在 Nix 的单用户安装上安装 Nix 插件，请在安装 nix-doc 后，将以下内容添加到您的 Nix 配置文件 ~/.config/nix/nix.conf 中

plugin-files = /home/YOURUSERNAMEHERE/.nix-profile/lib/libnix_doc_plugin.so

对于多用户安装，您需要执行类似以下操作

$ sudo ln -s $(nix-build '<nixpkgs>' -A nix-doc) /opt/nix-doc

然后将其放入您的 /etc/nix/nix.conf

plugin-files = /opt/nix-doc/lib/libnix_doc_plugin.so

NixOS 安装

使用 nix.extraOptions 链接插件文件

{ pkgs, ... }:

{
  nix.extraOptions = ''
    plugin-files = ${pkgs.nix-doc}/lib/libnix_doc_plugin.so
  '';

  environment.systemPackages = with pkgs; [
    nix-doc
  ];
}

使用方法

CLI

nix-doc <command>

nix-doc tags[dir]

在当前目录下生成一个与 vim 兼容的 tags 文件，用于目录下所有的 nix 脚本文件。

示例

nixpkgs$ nix-doc tags

nixpkgs$ file tags
tags: Exuberant Ctags tag file, ASCII text, with very long lines (502)

# opens vim to the function callCabal2nix
nixpkgs$ vim -t callCabal2nix

nix-doc search<regex> [dir]

示例输出

nixpkgs$ nix-doc search callPackage
   Call the package function in the file `fn' with the required
   arguments automatically.  The function is called with the
   arguments `args', but any missing arguments are obtained from
   `autoArgs'.  This function is intended to be partially
   parameterised, e.g.,

   callPackage = callPackageWith pkgs;
   pkgs = {
   libfoo = callPackage ./foo.nix { };
   libbar = callPackage ./bar.nix { };
   };

   If the `libbar' function expects an argument named `libfoo', it is
   automatically passed as an argument.  Overrides or missing
   arguments can be supplied in `args', e.g.

   libbar = callPackage ./bar.nix {
   libfoo = null;
   enableX11 = true;
   };
callPackageWith = autoArgs: fn: args: ...
# ./lib/customisation.nix:117
─────────────────────────────────────────────
   Like callPackage, but for a function that returns an attribute
   set of derivations. The override function is added to the
   individual attributes.
callPackagesWith = autoArgs: fn: args: ...
# ./lib/customisation.nix:127
─────────────────────────────────────────────
   Similar to callPackageWith/callPackage, but without makeOverridable
callPackageWith = autoArgs: fn: args: ...
# ./pkgs/development/beam-modules/lib.nix:7

Nix 插件

Nix 插件提供三个内置函数

内置函数.doc f

将函数 f 的文档打印到屏幕。返回 null。

内置函数.getDoc f

返回函数 f 的文档消息作为字符串（与 builtins.doc 的输出完全相同，只是作为字符串）。

内置函数.unsafeGetLambdaPos

NixOS/Nix#3912 的后端口。以类似 unsafeGetAttrPos 为属性获取位置的方式返回 lambda 的位置。

示例用法

» nix repl
Welcome to Nix version 2.3.7. Type :? for help.

nix-repl> n=import <nixpkgs> {}

nix-repl> builtins.doc n.lib.callPackageWith
   Call the package function in the file `fn' with the required
   arguments automatically.  The function is called with the
   arguments `args', but any missing arguments are obtained from
   `autoArgs'.  This function is intended to be partially
   parameterised, e.g.,

     callPackage = callPackageWith pkgs;
     pkgs = {
       libfoo = callPackage ./foo.nix { };
       libbar = callPackage ./bar.nix { };
     };

   If the `libbar' function expects an argument named `libfoo', it is
   automatically passed as an argument.  Overrides or missing
   arguments can be supplied in `args', e.g.

     libbar = callPackage ./bar.nix {
       libfoo = null;
       enableX11 = true;
     };
func = autoArgs: fn: args: ...
# /nix/store/frpij1x0ihnyc4r5f7v0zxwpslkq6s27-nixpkgs-20.09pre237807.0dc87c6e54f/nixpkgs/lib/customisation.nix:117
null

开发

此存储库设置为包含插件和命令行工具/库的 Cargo 工作空间。

由于 Nix 不在 shell 环境之外提供库，因此无法在 Nix shell 之外构建插件。因此，建议在开发插件时使用 nix shell，如下所示

$ nix-shell
[nix-shell]$ cargo build
[nix-shell]$ cargo check
[nix-shell]$ cargo test
# etc

待办事项

• 技术：应将 rnix 更新到最新主要版本。

相关工作

• https://github.com/NixOS/nix/pull/1652：一个PR，基本上实现了与这个工具插件在Nix自身中相同的功能，但由于在文档注释中使用的语法存在分歧而被无限期推迟。
• https://github.com/tazjin/nixdoc：一个Rust工具，用于生成Nix库函数的DocBook文档。
• https://github.com/mlvzk/manix：这个工具的早期分支，更侧重于CLI使用，支持索引和更快的搜索。相比之下，它们的CLI更好，但它们不做标签或Nix插件。

项目信息

预期所有参与该项目的人都应遵守行为准则。