|
| 1 | +{ |
| 2 | + lib, |
| 3 | + config, |
| 4 | + options, |
| 5 | + pkgs, |
| 6 | + ... |
| 7 | +}: |
| 8 | +let |
| 9 | + inherit (config.docs._utils) |
| 10 | + mkOptionList |
| 11 | + ; |
| 12 | + |
| 13 | + # Gets the page that owns this option. |
| 14 | + # We can use `findFirst` because `pageScopes` is a sorted list. |
| 15 | + getPageFor = |
| 16 | + loc: (lib.findFirst (pair: lib.lists.hasPrefix pair.scope loc) null pageScopePairs).page or null; |
| 17 | + |
| 18 | + optionsLists = builtins.groupBy (opt: getPageFor opt.loc) (mkOptionList options); |
| 19 | + |
| 20 | + # A list of { page, scope } pairs, sorted by scope length (longest first) |
| 21 | + pageScopePairs = lib.pipe config.docs.optionPages [ |
| 22 | + (lib.mapAttrsToList ( |
| 23 | + name: page: { |
| 24 | + page = name; |
| 25 | + scopes = page.optionScopes; |
| 26 | + } |
| 27 | + )) |
| 28 | + (builtins.concatMap ({ page, scopes }: builtins.map (scope: { inherit page scope; }) scopes)) |
| 29 | + (lib.sortOn (pair: 0 - builtins.length pair.scope)) |
| 30 | + ]; |
| 31 | + |
| 32 | + # Custom type to simplify type checking & merging. |
| 33 | + # `listOf str` is overkill and problematic for our use-case. |
| 34 | + optionLocType = lib.mkOptionType { |
| 35 | + name = "option-loc"; |
| 36 | + description = "option location"; |
| 37 | + descriptionClass = "noun"; |
| 38 | + check = v: lib.isList v && lib.all lib.isString v; |
| 39 | + }; |
| 40 | + |
| 41 | + optionsPageModule = |
| 42 | + { name, config, ... }: |
| 43 | + { |
| 44 | + options = { |
| 45 | + enable = lib.mkOption { |
| 46 | + type = lib.types.bool; |
| 47 | + default = config.optionsList != [ ]; |
| 48 | + defaultText = lib.literalExpression ''optionsList != [ ]''; |
| 49 | + example = true; |
| 50 | + description = "Whether to define a page derived from this optionsPage."; |
| 51 | + }; |
| 52 | + optionsList = lib.mkOption { |
| 53 | + type = with lib.types; listOf raw; |
| 54 | + description = '' |
| 55 | + List of options matching `scopes`. |
| 56 | + ''; |
| 57 | + readOnly = true; |
| 58 | + }; |
| 59 | + optionsJSON = lib.mkOption { |
| 60 | + type = lib.types.package; |
| 61 | + description = '' |
| 62 | + `options.json` file, as expected by `nixos-render-docs`. |
| 63 | + ''; |
| 64 | + readOnly = true; |
| 65 | + }; |
| 66 | + page = lib.mkOption { |
| 67 | + type = lib.types.deferredModule; |
| 68 | + description = '' |
| 69 | + The `page` module, to be assigned to `docs.pages.<name>`. |
| 70 | + ''; |
| 71 | + defaultText = lib.literalMD '' |
| 72 | + Options derived from the outer options-page |
| 73 | + ''; |
| 74 | + }; |
| 75 | + }; |
| 76 | + |
| 77 | + config = |
| 78 | + let |
| 79 | + cfg = config; |
| 80 | + drvName = lib.replaceStrings [ "/" ] [ "-" ] name; |
| 81 | + # Convert the doc-options list into the structure required for options.json |
| 82 | + # See https://github.com/NixOS/nixpkgs/blob/e2078ef3/nixos/lib/make-options-doc/default.nix#L167-L176 |
| 83 | + optionsSet = builtins.listToAttrs ( |
| 84 | + builtins.map (opt: { |
| 85 | + inherit (opt) name; |
| 86 | + value = builtins.removeAttrs opt [ |
| 87 | + "name" |
| 88 | + "visible" |
| 89 | + "internal" |
| 90 | + ]; |
| 91 | + }) config.optionsList |
| 92 | + ); |
| 93 | + in |
| 94 | + { |
| 95 | + optionsJSON = builtins.toFile "options-${drvName}.json" ( |
| 96 | + builtins.unsafeDiscardStringContext (builtins.toJSON optionsSet) |
| 97 | + ); |
| 98 | + |
| 99 | + page = |
| 100 | + { config, ... }: |
| 101 | + { |
| 102 | + # TODO: should this be conditional on something? |
| 103 | + text = lib.mkMerge [ |
| 104 | + # TODO: title |
| 105 | + # TODO: description |
| 106 | + ]; |
| 107 | + # NOTE: use a _really_ high override priority because there will |
| 108 | + # be another definition with the same prio as `text` |
| 109 | + source = lib.mkIf (cfg.optionsList != [ ]) ( |
| 110 | + lib.mkOverride 1 ( |
| 111 | + pkgs.callPackage ./render-page.nix { |
| 112 | + inherit (config) text; |
| 113 | + inherit (cfg) optionsJSON; |
| 114 | + name = drvName; |
| 115 | + } |
| 116 | + ) |
| 117 | + ); |
| 118 | + }; |
| 119 | + }; |
| 120 | + }; |
| 121 | + |
| 122 | + optionsPageType = lib.types.submodule ( |
| 123 | + { name, ... }: |
| 124 | + { |
| 125 | + imports = [ |
| 126 | + optionsPageModule |
| 127 | + ]; |
| 128 | + options.optionScopes = lib.mkOption { |
| 129 | + type = with lib.types; coercedTo optionLocType lib.singleton (nonEmptyListOf optionLocType); |
| 130 | + description = '' |
| 131 | + A list of option-locations to be included in this page. |
| 132 | + ''; |
| 133 | + }; |
| 134 | + config = { |
| 135 | + optionsList = optionsLists.${name} or [ ]; |
| 136 | + page.menu.section = lib.mkDefault "options"; |
| 137 | + }; |
| 138 | + } |
| 139 | + ); |
| 140 | + |
| 141 | + checkDocs = |
| 142 | + value: |
| 143 | + let |
| 144 | + duplicates = lib.pipe value [ |
| 145 | + builtins.attrValues |
| 146 | + (builtins.concatMap (doc: doc.optionScopes)) |
| 147 | + (builtins.groupBy lib.showOption) |
| 148 | + (lib.mapAttrs (_: builtins.length)) |
| 149 | + (lib.filterAttrs (_: count: count > 1)) |
| 150 | + ]; |
| 151 | + in |
| 152 | + assert lib.assertMsg (duplicates == { }) '' |
| 153 | + `docs.options` has conflicting `optionScopes` definitions: |
| 154 | + ${lib.concatMapAttrsStringSep "\n" ( |
| 155 | + name: count: "- `${name}' defined ${toString count} times" |
| 156 | + ) duplicates} |
| 157 | + Definitions:${lib.options.showDefs options.docs.options.definitionsWithLocations} |
| 158 | + ''; |
| 159 | + value; |
| 160 | +in |
| 161 | +{ |
| 162 | + options.docs = { |
| 163 | + optionPages = lib.mkOption { |
| 164 | + type = with lib.types; lazyAttrsOf optionsPageType; |
| 165 | + description = '' |
| 166 | + A set of option scopes to include in the docs. |
| 167 | +
|
| 168 | + Each enabled options page will produce a corresponding `pages` page. |
| 169 | + ''; |
| 170 | + default = { }; |
| 171 | + apply = checkDocs; |
| 172 | + }; |
| 173 | + }; |
| 174 | + config.docs = { |
| 175 | + # Define pages for each "optionPages" attr |
| 176 | + pages = lib.pipe config.docs.optionPages [ |
| 177 | + (lib.filterAttrs (_: v: v.enable)) |
| 178 | + (builtins.mapAttrs (_: cfg: cfg.page)) |
| 179 | + ]; |
| 180 | + }; |
| 181 | +} |
0 commit comments