From 67ec6371d5d38224f10432dcf4d10eacd85cc13b Mon Sep 17 00:00:00 2001
From: Jan Malakhovski <oxij@oxij.org>
Date: Wed, 20 Apr 2016 21:57:33 +0000
Subject: nixos, lib: implement relatedPackages option

This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.
---
 nixos/doc/manual/default.nix | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

(limited to 'nixos/doc/manual/default.nix')

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 9a96f201a397..95363c2458f5 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -15,13 +15,27 @@ let
     else if builtins.isFunction x then "<function>"
     else x;
 
-  # Clean up declaration sites to not refer to the NixOS source tree.
+  # Generate DocBook documentation for a list of packages
+  genRelatedPackages = packages:
+    let
+      unpack = p: if lib.isString p then { name = p; } else p;
+      describe = { name, package ? pkgs.${name}, comment ? "" }:
+          "<listitem>"
+        + "<para><option>pkgs.${name}</option> (${package.name}): ${package.meta.description or "???"}.</para>"
+        + lib.optionalString (comment != "") "\n<para>${comment}</para>"
+        # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>
+        + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>"
+        + "</listitem>";
+    in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>";
+
   optionsList' = lib.flip map optionsList (opt: opt // {
+    # Clean up declaration sites to not refer to the NixOS source tree.
     declarations = map stripAnyPrefixes opt.declarations;
   }
   // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; }
   // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; }
-  // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; });
+  // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; }
+  // lib.optionalAttrs (opt ? relatedPackages) { relatedPackages = genRelatedPackages opt.relatedPackages; });
 
   # We need to strip references to /nix/store/* from options,
   # including any `extraSources` if some modules came from elsewhere,
-- 
cgit 1.4.1