From a7d75ab6489dc5834e8402db374b4d0f1e774d53 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 | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) (limited to 'nixos/doc/manual') diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 8079a2feb29f..9ee70ba59b79 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -6,7 +6,7 @@ let lib = pkgs.lib; # Remove invisible and internal options. - optionsList = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options); + optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options); # Replace functions by the string substFunction = x: @@ -16,7 +16,7 @@ let else x; # Clean up declaration sites to not refer to the NixOS source tree. - optionsList' = lib.flip map optionsList (opt: opt // { + optionsListDesc = lib.flip map optionsListVisible (opt: opt // { declarations = map stripAnyPrefixes opt.declarations; } // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; } @@ -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) optionsListDesc; + # 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} @@ -191,7 +205,7 @@ in rec { mkdir -p $dst cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON - (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList')))) + (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList)))) } $dst/options.json mkdir -p $out/nix-support -- cgit 1.4.1 From 660806066abc4a64ac44b53b2b1a20f5ab4d920b 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. 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(-) (limited to 'nixos/doc/manual') diff --git a/lib/options.nix b/lib/options.nix index 769d3cc55723..e10c86dd5064 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 9ee70ba59b79..66fa4f0ba43c 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 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