5 unstable releases

0.5.1 Jul 9, 2021
0.5.0 Jul 4, 2021
0.3.0 Aug 9, 2020
0.2.2 Aug 6, 2020
0.2.1 Aug 6, 2020

#1600 in Command line utilities

LGPL-3.0-or-later

33KB
823 lines

nix-doc

A Nix documentation search tool. This package provides two front ends for documentation lookup: a Nix plugin that allows access to documentation directly from nix repl and a command line tool.

Setup

# nix-doc is in nixpkgs
$ nix-env -i nix-doc
# you can also 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)
$ cargo install nix-doc

Nix Plugin

To install the Nix plugin, add this to your Nix config at ~/.config/nix/nix.conf after installing nix-doc with nix-env:

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

NixOS Installation

Link the plugin file using nix.extraOptions:

{ pkgs, ... }:

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

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

Usage

CLI

nix-doc SearchRegex [Directory]

Example output:

nixpkgs$ nix-doc 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 plugin

The Nix plugin provides three builtins:

builtins.doc f

Prints the documentation of the function f to the screen. Returns null.

builtins.getDoc f

Returns the documentation message for the function f as a string (exactly the same output as builtins.doc, just as a string).

builtins.unsafeGetLambdaPos

A backport of NixOS/Nix#3912. Returns the position of a lambda, in a similar fashion to unsafeGetAttrPos for attributes.

Sample usage:

» 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

Development

This repository is set up as a Cargo workspace with the plugin and the command line tool/library as parts.

It is not really possible to build the plugin outside a Nix shell since Nix does not provide libraries outside the shell environment. As such, it is suggested to use a nix shell while developing the plugin as follows:

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

TODO

  • Generate tags files/otherwise generate a database file to speed up result generation.

Related work

Project information

Everyone is expected to follow the code of conduct while participating in this project.

Dependencies

~3.5–4.5MB
~93K SLoC