repl: improve :doc builtin repl command to support lambdas.

For a long time `nix repl` has supported displaying documentation set on
builtins, however, it has long been convention to use Markdown comments
on Nix functions themselves for documentation. This exposes that
information to `nix repl` users in a nice and formatted way.

NixOS/rfcs#145 doc-comments are primarily what this feature is intended
to consume, however, support for lambda documentation in the repl is
experimental. We do our best effort to support the RFC here.

These changes are based on [the nix-doc library](https://github.com/lf-/nix-doc) and
are licensed under the terms described in the relevant source files.

Change-Id: Ic6fe947d39a22540705d890737e336c4720b0a22

Makefile.config.in

@@ -19,6 +19,7 @@ LIBBROTLI_LIBS = @LIBBROTLI_LIBS@
 LIBCURL_LIBS = @LIBCURL_LIBS@
 LIBSECCOMP_LIBS = @LIBSECCOMP_LIBS@
 LOWDOWN_LIBS = @LOWDOWN_LIBS@
+NIXDOC_LIBS = -lnix_doc
 OPENSSL_LIBS = @OPENSSL_LIBS@
 PACKAGE_NAME = @PACKAGE_NAME@
 PACKAGE_VERSION = @PACKAGE_VERSION@

doc/manual/rl-next/repl-doc-command.md

@@ -0,0 +1,13 @@
+---
+synopsis: Experimental REPL support for documentation comments using `:doc`
+cls: 564
+---
+
+Using `:doc` in the REPL now supports showing documentation comments when defined on a function.
+
+Previously this was only able to document builtins, however it now will show comments defined on a lambda as well.
+
+This support is experimental and relies on an embedded version of [nix-doc](https://github.com/lf-/nix-doc).
+
+The logic also supports limited Markdown formatting of doccomments and should easily support any [RFC 145](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md)
+compatible documentation comments in addition to simple commented documentation.

flake.nix

@@ -198,11 +198,14 @@
             '';
           };
 
+          nix-doc = final.callPackage ./nix-doc/package.nix {};
+
           nix = final.callPackage ./package.nix {
             inherit versionSuffix fileset;
             stdenv = currentStdenv;
             boehmgc = final.boehmgc-nix;
             busybox-sandbox-shell = final.busybox-sandbox-shell or final.default-busybox-sandbox-shell;
+            nix-doc = final.nix-doc;
           };
         };
 

maintainers/build-release-notes.py

@@ -38,7 +38,7 @@ def format_cl(cl: str) -> str:
     try:
         e = frontmatter.load(p)
         if 'synopsis' not in e.metadata:
-            raise Exception('missing synposis')
+            raise Exception('missing synopsis')
         unknownKeys = set(e.metadata.keys()) - set(('synopsis', 'cls', 'issues', 'prs', 'significance'))
         if unknownKeys:
             raise Exception('unknown keys', unknownKeys)

meson.build

@@ -219,6 +219,11 @@ deps += toml11
 nlohmann_json = dependency('nlohmann_json', required : true)
 deps += nlohmann_json
 
+# nix-doc is a Rust project provided via buildInputs and unfortunately doesn't have any way to be detected.
+# Just declare it manually to resolve this.
+nix_doc = declare_dependency(link_args : [ '-lnix_doc' ])
+deps += nix_doc
+
 #
 # Build-time tools
 #

nix-doc/.gitignore

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2024 Jade Lovelace
+#
+# SPDX-License-Identifier: BSD-2-Clause OR MIT
+
+/target
+result

nix-doc/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+description = "Nix documentation grepping tool"
+edition = "2018"
+name = "nix-doc"
+version = "0.0.1"
+license = "BSD-2-Clause OR MIT"
+homepage = "https://github.com/lf-/nix-doc"
+repository = "https://github.com/lf-/nix-doc"
+
+[lib]
+crate_type = ["staticlib"]
+
+[dependencies]
+rnix = "0.8.0"
+
+[dev-dependencies]
+expect-test = "1.1.0"

nix-doc/package.nix

@@ -0,0 +1,11 @@
+{
+  rustPlatform,
+  lib
+}:
+
+rustPlatform.buildRustPackage {
+  name = "nix-doc";
+
+  cargoHash = "sha256-HXL235loBJnRje7KaMCCCTighv6WNYRrZ/jgkAQbEY0=";
+  src = lib.cleanSource ./.;
+}