From 182463dc79bb8dd4ca09ae54e8fcc1637d501c6a Mon Sep 17 00:00:00 2001 From: Jan Malakhovski Date: Wed, 20 Apr 2016 21:46:02 +0000 Subject: nixos/doc: push all the `enable*' and `package*` options to the top of their option group Why? Because this way configuration.nix(5) can be read linearly. Before: > virtualisation.xen.bootParams > ... > virtualisation.xen.enable > ... > virtualisation.xen.package > ... After: > virtualisation.xen.enable > virtualisation.xen.package > virtualisation.xen.bootParams > ... --- nixos/doc/manual/default.nix | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'nixos/doc') diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 9bc83be66104..9a96f201a397 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -32,8 +32,22 @@ let prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip; + # Custom "less" that pushes up all the things ending in ".enable*" + # and ".package" + optionListLess = a: b: + let + splt = lib.splitString "."; + ise = lib.hasPrefix "enable"; + isp = lib.hasPrefix "package"; + cmp = lib.splitByAndCompare ise lib.compare + (lib.splitByAndCompare isp lib.compare lib.compare); + in lib.compareLists cmp (splt a) (splt b) < 0; + + # Customly sort option list for the man page. + optionsList'' = lib.sort (a: b: optionListLess a.name b.name) optionsList'; + # Convert the list of options into an XML file. - optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList'); + optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList''); optionsDocBook = runCommand "options-db.xml" {} '' optionsXML=${optionsXML} -- cgit 1.4.1 From 67ec6371d5d38224f10432dcf4d10eacd85cc13b Mon Sep 17 00:00:00 2001 From: Jan Malakhovski 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. --- lib/options.nix | 9 +++++---- nixos/doc/manual/default.nix | 18 ++++++++++++++++-- nixos/doc/manual/options-to-docbook.xsl | 9 +++++++++ 3 files changed, 30 insertions(+), 6 deletions(-) (limited to 'nixos/doc') diff --git a/lib/options.nix b/lib/options.nix index 769d3cc55723..ab1201c718a0 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. , 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 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 "" 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 ? "" }: + "" + + " (${package.name}): ${package.meta.description or "???"}." + + lib.optionalString (comment != "") "\n${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)}"; + 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, diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl index 5387546b5982..7b45b233ab2a 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: -- cgit 1.4.1