commit 660806066abc4a64ac44b53b2b1a20f5ab4d920b · pyrox.dev/nixpkgs

+5 -4

lib/options.nix

···

       14
       14
        
           , defaultText ? null # Textual representation of the default, for in the manual.

     

       15
       15
        
           , example ? null # Example value used in the manual.

     

       16
       16
        
           , description ? null # String describing the option.

     

       17
       17
       +
           , relatedPackages ? null # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix).

     

       17
       18
        
           , type ? null # Option type, providing type-checking and value merging.

     

       18
       19
        
           , apply ? null # Function that converts the option value to something else.

     

       19
       20
        
           , internal ? null # Whether the option is for NixOS developers only.

     
···

       76
       77
        
         getValues = map (x: x.value);

     

       77
       78
        
         getFiles = map (x: x.file);

     

       78
       79
        
       

     

       79
       79
       -
       

     

       80
       80
        
         # Generate documentation template from the list of option declaration like

     

       81
       81
        
         # the set generated with filterOptionSets.

     

       82
       82
        
         optionAttrSetToDocList = optionAttrSetToDocList' [];

     
···

       93
       93
        
                 readOnly = opt.readOnly or false;

     

       94
       94
        
                 type = opt.type.description or null;

     

       95
       95
        
               }

     

       96
       96
       -
               // (if opt ? example then { example = scrubOptionValue opt.example; } else {})

     

       97
       97
       -
               // (if opt ? default then { default = scrubOptionValue opt.default; } else {})

     

       98
       98
       -
               // (if opt ? defaultText then { default = opt.defaultText; } else {});

     

       96
       96
       +
               // optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; }

     

       97
       97
       +
               // optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; }

     

       98
       98
       +
               // optionalAttrs (opt ? defaultText) { default = opt.defaultText; }

     

       99
       99
       +
               // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; };

     

       99
       100
        
       

     

       100
       101
        
               subOptions =

     

       101
       102
        
                 let ss = opt.type.getSubOptions opt.loc;

+32 -2

nixos/doc/manual/default.nix

···

       15
       15
        
           else if lib.isFunction x then "<function>"

     

       16
       16
        
           else x;

     

       17
       17
        
       

     

       18
       18
       -
         # Clean up declaration sites to not refer to the NixOS source tree.

     

       18
       18
       +
         # Generate DocBook documentation for a list of packages. This is

     

       19
       19
       +
         # what `relatedPackages` option of `mkOption` from

     

       20
       20
       +
         # ../../../lib/options.nix influences.

     

       21
       21
       +
         #

     

       22
       22
       +
         # Each element of `relatedPackages` can be either

     

       23
       23
       +
         # - a string:  that will be interpreted as an attribute name from `pkgs`,

     

       24
       24
       +
         # - a list:    that will be interpreted as an attribute path from `pkgs`,

     

       25
       25
       +
         # - an attrset: that can specify `name`, `path`, `package`, `comment`

     

       26
       26
       +
         #   (either of `name`, `path` is required, the rest are optional).

     

       27
       27
       +
         genRelatedPackages = packages:

     

       28
       28
       +
           let

     

       29
       29
       +
             unpack = p: if lib.isString p then { name = p; }

     

       30
       30
       +
                         else if lib.isList p then { path = p; }

     

       31
       31
       +
                         else p;

     

       32
       32
       +
             describe = args:

     

       33
       33
       +
               let

     

       34
       34
       +
                 name = args.name or (lib.concatStringsSep "." args.path);

     

       35
       35
       +
                 path = args.path or [ args.name ];

     

       36
       36
       +
                 package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs);

     

       37
       37
       +
               in "<listitem>"

     

       38
       38
       +
               + "<para><literal>pkgs.${name} (${package.meta.name})</literal>"

     

       39
       39
       +
               + lib.optionalString (!package.meta.evaluates) " <emphasis>[UNAVAILABLE]</emphasis>"

     

       40
       40
       +
               + ": ${package.meta.description or "???"}.</para>"

     

       41
       41
       +
               + lib.optionalString (args ? comment) "\n<para>${args.comment}</para>"

     

       42
       42
       +
               # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>

     

       43
       43
       +
               + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>"

     

       44
       44
       +
               + "</listitem>";

     

       45
       45
       +
           in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>";

     

       46
       46
       +
       

     

       19
       47
        
         optionsListDesc = lib.flip map optionsListVisible (opt: opt // {

     

       48
       48
       +
           # Clean up declaration sites to not refer to the NixOS source tree.

     

       20
       49
        
           declarations = map stripAnyPrefixes opt.declarations;

     

       21
       50
        
         }

     

       22
       51
        
         // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; }

     

       23
       52
        
         // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; }

     

       24
       24
       -
         // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; });

     

       53
       53
       +
         // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; }

     

       54
       54
       +
         // lib.optionalAttrs (opt ? relatedPackages) { relatedPackages = genRelatedPackages opt.relatedPackages; });

     

       25
       55
        
       

     

       26
       56
        
         # We need to strip references to /nix/store/* from options,

     

       27
       57
        
         # including any `extraSources` if some modules came from elsewhere,

nixos/doc/manual/options-to-docbook.xsl

···

       70
       70
        
                       </para>

     

       71
       71
        
                     </xsl:if>

     

       72
       72
        
       

     

       73
       73
       +
                     <xsl:if test="attr[@name = 'relatedPackages']">

     

       74
       74
       +
                       <para>

     

       75
       75
       +
                         <emphasis>Related packages:</emphasis>

     

       76
       76
       +
                         <xsl:text> </xsl:text>

     

       77
       77
       +
                         <xsl:value-of disable-output-escaping="yes"

     

       78
       78
       +
                                       select="attr[@name = 'relatedPackages']/string/@value" />

     

       79
       79
       +
                       </para>

     

       80
       80
       +
                     </xsl:if>

     

       81
       81
       +
       

     

       73
       82
        
                     <xsl:if test="count(attr[@name = 'declarations']/list/*) != 0">

     

       74
       83
        
                       <para>

     

       75
       84
        
                         <emphasis>Declared by:</emphasis>