From 660806066abc4a64ac44b53b2b1a20f5ab4d920b Mon Sep 17 00:00:00 2001 From: Jan Malakhovski Date: Wed, 20 Apr 2016 21:57:33 +0000 Subject: [PATCH] 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. See the next several commits for examples. --- lib/options.nix | 9 ++++--- nixos/doc/manual/default.nix | 34 +++++++++++++++++++++++-- nixos/doc/manual/options-to-docbook.xsl | 9 +++++++ 3 files changed, 46 insertions(+), 6 deletions(-) diff --git a/lib/options.nix b/lib/options.nix index 769d3cc5572..e10c86dd506 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -14,6 +14,7 @@ rec { , defaultText ? null # Textual representation of the default, for in the manual. , example ? null # Example value used in the manual. , description ? null # String describing the option. + , relatedPackages ? null # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix). , type ? null # Option type, providing type-checking and value merging. , apply ? null # Function that converts the option value to something else. , internal ? null # Whether the option is for NixOS developers only. @@ -76,7 +77,6 @@ rec { getValues = map (x: x.value); getFiles = map (x: x.file); - # Generate documentation template from the list of option declaration like # the set generated with filterOptionSets. optionAttrSetToDocList = optionAttrSetToDocList' []; @@ -93,9 +93,10 @@ rec { readOnly = opt.readOnly or false; type = opt.type.description or null; } - // (if opt ? example then { example = scrubOptionValue opt.example; } else {}) - // (if opt ? default then { default = scrubOptionValue opt.default; } else {}) - // (if opt ? defaultText then { default = opt.defaultText; } else {}); + // optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; } + // optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; } + // optionalAttrs (opt ? defaultText) { default = opt.defaultText; } + // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; }; subOptions = let ss = opt.type.getSubOptions opt.loc; diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 9ee70ba59b7..66fa4f0ba43 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -15,13 +15,43 @@ let else if lib.isFunction x then "" else x; - # Clean up declaration sites to not refer to the NixOS source tree. + # Generate DocBook documentation for a list of packages. This is + # what `relatedPackages` option of `mkOption` from + # ../../../lib/options.nix influences. + # + # Each element of `relatedPackages` can be either + # - a string: that will be interpreted as an attribute name from `pkgs`, + # - a list: that will be interpreted as an attribute path from `pkgs`, + # - an attrset: that can specify `name`, `path`, `package`, `comment` + # (either of `name`, `path` is required, the rest are optional). + genRelatedPackages = packages: + let + unpack = p: if lib.isString p then { name = p; } + else if lib.isList p then { path = p; } + else p; + describe = args: + let + name = args.name or (lib.concatStringsSep "." args.path); + path = args.path or [ args.name ]; + package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs); + in "" + + "pkgs.${name} (${package.meta.name})" + + lib.optionalString (!package.meta.evaluates) " [UNAVAILABLE]" + + ": ${package.meta.description or "???"}." + + lib.optionalString (args ? comment) "\n${args.comment}" + # Lots of `longDescription's break DocBook, so we just wrap them into + + lib.optionalString (package.meta ? longDescription) "\n${package.meta.longDescription}" + + ""; + in "${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}"; + optionsListDesc = lib.flip map optionsListVisible (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, diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl index 5387546b598..7b45b233ab2 100644 --- a/nixos/doc/manual/options-to-docbook.xsl +++ b/nixos/doc/manual/options-to-docbook.xsl @@ -70,6 +70,15 @@ + + + Related packages: + + + + + Declared by: