commit 15c41e1d54fca9ba6f3c7fbaf294b8af139fbca2 · pyrox.dev/nixpkgs

+1 -1

nixos/doc/manual/default.nix

···

       161
        
       in rec {

     

       162
        
         inherit generatedSources;

     

       163
        
       

     

       164
       -
         inherit (optionsDoc) optionsJSON optionsXML optionsDocBook;

     

       165
        
       

     

       166
        
         # Generate the NixOS manual.

     

       167
        
         manualHTML = runCommand "nixos-manual-html"

···

       161
        
       in rec {

     

       162
        
         inherit generatedSources;

     

       163
        
       

     

       164
       +
         inherit (optionsDoc) optionsJSON optionsDocBook;

     

       165
        
       

     

       166
        
         # Generate the NixOS manual.

     

       167
        
         manualHTML = runCommand "nixos-manual-html"

+37 -90

nixos/lib/make-options-doc/default.nix

···

       24
        
       }:

     

       25
        
       

     

       26
        
       let

     

       27
       -
         # Replace functions by the string <function>

     

       28
       -
         substFunction = x:

     

       29
       -
           if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x

     

       30
       -
           else if builtins.isList x then map substFunction x

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

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

     

       32
        
           else x;

     

       33
        
       

     

       34
       -
         optionsListDesc = lib.flip map optionsListVisible

     

       35
        
          (opt: transformOptions opt

     

       36
       -
           // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; }

     

       37
       -
           // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; }

     

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

     

       39
        
           // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages opt.name; }

     

       40
        
          );

     

       41
        
       

     
···

       69
        
               + "</listitem>";

     

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

     

       71
        
       

     

       72
       -
         # Custom "less" that pushes up all the things ending in ".enable*"

     

       73
       -
         # and ".package*"

     

       74
       -
         optionLess = a: b:

     

       75
       -
           let

     

       76
       -
             ise = lib.hasPrefix "enable";

     

       77
       -
             isp = lib.hasPrefix "package";

     

       78
       -
             cmp = lib.splitByAndCompare ise lib.compare

     

       79
       -
                                        (lib.splitByAndCompare isp lib.compare lib.compare);

     

       80
       -
           in lib.compareLists cmp a.loc b.loc < 0;

     

       81
       -
       

     

       82
        
         # Remove invisible and internal options.

     

       83
        
         optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options);

     

       84
        
       

     

       85
       -
         # Customly sort option list for the man page.

     

       86
       -
         # Always ensure that the sort order matches sortXML.py!

     

       87
       -
         optionsList = lib.sort optionLess optionsListDesc;

     

       88
       -
       

     

       89
       -
         # Convert the list of options into an XML file.

     

       90
       -
         # This file is *not* sorted sorted to save on eval time, since the docbook XML

     

       91
       -
         # and the manpage depend on it and thus we evaluate this on every system rebuild.

     

       92
       -
         optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsListDesc);

     

       93
       -
       

     

       94
        
         optionsNix = builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList);

     

       95
        
       

     

       96
       -
         # TODO: declarations: link to github

     

       97
       -
         singleAsciiDoc = name: value: ''

     

       98
       -
           == ${name}

     

       99
       -
       

     

       100
       -
           ${value.description}

     

       101
       -
       

     

       102
       -
           [discrete]

     

       103
       -
           === details

     

       104
        
       

     

       105
       -
           Type:: ${value.type}

     

       106
       -
           ${ if lib.hasAttr "default" value

     

       107
       -
              then ''

     

       108
       -
               Default::

     

       109
       -
               +

     

       110
       -
               ----

     

       111
       -
               ${builtins.toJSON value.default}

     

       112
       -
               ----

     

       113
       -
             ''

     

       114
       -
             else "No Default:: {blank}"

     

       115
       -
           }

     

       116
       -
           ${ if value.readOnly

     

       117
       -
              then "Read Only:: {blank}"

     

       118
       -
             else ""

     

       119
       -
           }

     

       120
       -
           ${ if lib.hasAttr "example" value

     

       121
       -
              then ''

     

       122
       -
               Example::

     

       123
       -
               +

     

       124
       -
               ----

     

       125
       -
               ${builtins.toJSON value.example}

     

       126
       -
               ----

     

       127
       -
             ''

     

       128
       -
             else "No Example:: {blank}"

     

       129
       -
           }

     

       130
        
         '';

     

       131
        
       

     

       132
       -
         singleMDDoc = name: value: ''

     

       133
       -
           ## ${lib.escape [ "<" ">" ] name}

     

       134
       -
           ${value.description}

     

       135
       -
       

     

       136
       -
           ${lib.optionalString (value ? type) ''

     

       137
       -
             *_Type_*:

     

       138
       -
             ${value.type}

     

       139
       -
           ''}

     

       140
       -
       

     

       141
       -
           ${lib.optionalString (value ? default) ''

     

       142
       -
             *_Default_*

     

       143
       -
             ```

     

       144
       -
             ${builtins.toJSON value.default}

     

       145
       -
             ```

     

       146
       -
           ''}

     

       147
       -
       

     

       148
       -
           ${lib.optionalString (value ? example) ''

     

       149
       -
             *_Example_*

     

       150
       -
             ```

     

       151
       -
             ${builtins.toJSON value.example}

     

       152
       -
             ```

     

       153
       -
           ''}

     

       154
        
         '';

     

       155
        
       

     

       156
       -
       in {

     

       157
       -
         inherit optionsNix;

     

       158
       -
       

     

       159
       -
         optionsAsciiDoc = lib.concatStringsSep "\n" (lib.mapAttrsToList singleAsciiDoc optionsNix);

     

       160
       -
       

     

       161
       -
         optionsMDDoc = lib.concatStringsSep "\n" (lib.mapAttrsToList singleMDDoc optionsNix);

     

       162
       -
       

     

       163
        
         optionsJSON = pkgs.runCommand "options.json"

     

       164
        
           { meta.description = "List of NixOS options in JSON format";

     

       165
        
             buildInputs = [ pkgs.brotli ];

     
···

       176
        
             mkdir -p $out/nix-support

     

       177
        
             echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products

     

       178
        
             echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products

     

       179
       -
           ''; # */

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       180
        
       

     

       181
        
         optionsDocBook = pkgs.runCommand "options-docbook.xml" {} ''

     

       182
        
           optionsXML=${optionsXML}

···

       24
        
       }:

     

       25
        
       

     

       26
        
       let

     

       27
       +
         # Make a value safe for JSON. Functions are replaced by the string "<function>",

     

       28
       +
         # derivations are replaced with an attrset

     

       29
       +
         # { _type = "derivation"; name = <name of that derivation>; }.

     

       30
       +
         # We need to handle derivations specially because consumers want to know about them,

     

       31
       +
         # but we can't easily use the type,name subset of keys (since type is often used as

     

       32
       +
         # a module option and might cause confusion). Use _type,name instead to the same

     

       33
       +
         # effect, since _type is already used by the module system.

     

       34
       +
         substSpecial = x:

     

       35
       +
           if lib.isDerivation x then { _type = "derivation"; name = x.name; }

     

       36
       +
           else if builtins.isAttrs x then lib.mapAttrs (name: substSpecial) x

     

       37
       +
           else if builtins.isList x then map substSpecial x

     

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

     

       39
        
           else x;

     

       40
        
       

     

       41
       +
         optionsList = lib.flip map optionsListVisible

     

       42
        
          (opt: transformOptions opt

     

       43
       +
           // lib.optionalAttrs (opt ? example) { example = substSpecial opt.example; }

     

       44
       +
           // lib.optionalAttrs (opt ? default) { default = substSpecial opt.default; }

     

       45
       +
           // lib.optionalAttrs (opt ? type) { type = substSpecial opt.type; }

     

       46
        
           // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages opt.name; }

     

       47
        
          );

     

       48
        
       

     
···

       76
        
               + "</listitem>";

     

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

     

       78
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       79
        
         # Remove invisible and internal options.

     

       80
        
         optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options);

     

       81
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       82
        
         optionsNix = builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList);

     

       83
        
       

     

       84
       +
       in rec {

     

       85
       +
         inherit optionsNix;

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       86
        
       

     

       87
       +
         optionsAsciiDoc = pkgs.runCommand "options.adoc" {} ''

     

       88
       +
           ${pkgs.python3Minimal}/bin/python ${./generateAsciiDoc.py} \

     

       89
       +
             < ${optionsJSON}/share/doc/nixos/options.json \

     

       90
       +
             > $out

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       91
        
         '';

     

       92
        
       

     

       93
       +
         optionsCommonMark = pkgs.runCommand "options.md" {} ''

     

       94
       +
           ${pkgs.python3Minimal}/bin/python ${./generateCommonMark.py} \

     

       95
       +
             < ${optionsJSON}/share/doc/nixos/options.json \

     

       96
       +
             > $out

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       97
        
         '';

     

       98
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       99
        
         optionsJSON = pkgs.runCommand "options.json"

     

       100
        
           { meta.description = "List of NixOS options in JSON format";

     

       101
        
             buildInputs = [ pkgs.brotli ];

     
···

       112
        
             mkdir -p $out/nix-support

     

       113
        
             echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products

     

       114
        
             echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products

     

       115
       +
           '';

     

       116
       +
       

     

       117
       +
         # Convert options.json into an XML file.

     

       118
       +
         # The actual generation of the xml file is done in nix purely for the convenience

     

       119
       +
         # of not having to generate the xml some other way

     

       120
       +
         optionsXML = pkgs.runCommand "options.xml" {} ''

     

       121
       +
           ${pkgs.nix}/bin/nix-instantiate \

     

       122
       +
             --store dummy:// \

     

       123
       +
             --eval --xml --strict ${./optionsJSONtoXML.nix} \

     

       124
       +
             --argstr file ${optionsJSON}/share/doc/nixos/options.json \

     

       125
       +
             > "$out"

     

       126
       +
         '';

     

       127
        
       

     

       128
        
         optionsDocBook = pkgs.runCommand "options-docbook.xml" {} ''

     

       129
        
           optionsXML=${optionsXML}

+37

nixos/lib/make-options-doc/generateAsciiDoc.py

···

       1
       +
       import json

     

       2
       +
       import sys

     

       3
       +
       

     

       4
       +
       options = json.load(sys.stdin)

     

       5
       +
       # TODO: declarations: link to github

     

       6
       +
       for (name, value) in options.items():

     

       7
       +
           print(f'== {name}')

     

       8
       +
           print()

     

       9
       +
           print(value['description'])

     

       10
       +
           print()

     

       11
       +
           print('[discrete]')

     

       12
       +
           print('=== details')

     

       13
       +
           print()

     

       14
       +
           print(f'Type:: {value["type"]}')

     

       15
       +
           if 'default' in value:

     

       16
       +
               print('Default::')

     

       17
       +
               print('+')

     

       18
       +
               print('----')

     

       19
       +
               print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))

     

       20
       +
               print('----')

     

       21
       +
               print()

     

       22
       +
           else:

     

       23
       +
               print('No Default:: {blank}')

     

       24
       +
           if value['readOnly']:

     

       25
       +
               print('Read Only:: {blank}')

     

       26
       +
           else:

     

       27
       +
               print()

     

       28
       +
           if 'example' in value:

     

       29
       +
               print('Example::')

     

       30
       +
               print('+')

     

       31
       +
               print('----')

     

       32
       +
               print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))

     

       33
       +
               print('----')

     

       34
       +
               print()

     

       35
       +
           else:

     

       36
       +
               print('No Example:: {blank}')

     

       37
       +
           print()

+27

nixos/lib/make-options-doc/generateCommonMark.py

···

       1
       +
       import json

     

       2
       +
       import sys

     

       3
       +
       

     

       4
       +
       options = json.load(sys.stdin)

     

       5
       +
       for (name, value) in options.items():

     

       6
       +
           print('##', name.replace('<', '\\<').replace('>', '\\>'))

     

       7
       +
           print(value['description'])

     

       8
       +
           print()

     

       9
       +
           if 'type' in value:

     

       10
       +
               print('*_Type_*:')

     

       11
       +
               print(value['type'])

     

       12
       +
               print()

     

       13
       +
           print()

     

       14
       +
           if 'default' in value:

     

       15
       +
               print('*_Default_*')

     

       16
       +
               print('```')

     

       17
       +
               print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))

     

       18
       +
               print('```')

     

       19
       +
           print()

     

       20
       +
           print()

     

       21
       +
           if 'example' in value:

     

       22
       +
               print('*_Example_*')

     

       23
       +
               print('```')

     

       24
       +
               print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))

     

       25
       +
               print('```')

     

       26
       +
           print()

     

       27
       +
           print()

+1 -1

nixos/lib/make-options-doc/options-to-docbook.xsl

···

       189
        
         </xsl:template>

     

       190
        
       

     

       191
        
       

     

       192
       -
         <xsl:template match="derivation">

     

       193
        
           <replaceable>(build of <xsl:value-of select="attr[@name = 'name']/string/@value" />)</replaceable>

     

       194
        
         </xsl:template>

     

       195

···

       189
        
         </xsl:template>

     

       190
        
       

     

       191
        
       

     

       192
       +
         <xsl:template match="attrs[attr[@name = '_type' and string[@value = 'derivation']]]">

     

       193
        
           <replaceable>(build of <xsl:value-of select="attr[@name = 'name']/string/@value" />)</replaceable>

     

       194
        
         </xsl:template>

     

       195

nixos/lib/make-options-doc/optionsJSONtoXML.nix

···

       1
       +
       { file }:

     

       2
       +
       

     

       3
       +
       builtins.attrValues

     

       4
       +
         (builtins.mapAttrs

     

       5
       +
           (name: def: def // { inherit name; })

     

       6
       +
           (builtins.fromJSON (builtins.readFile file)))

-1

nixos/lib/make-options-doc/sortXML.py

···

       19
        
               for p in opt.findall('attr[@name="loc"]/list/string')

     

       20
        
           ]

     

       21
        
       

     

       22
       -
       # always ensure that the sort order matches the order used in the nix expression!

     

       23
        
       options.sort(key=sortKey)

     

       24
        
       

     

       25
        
       doc = ET.Element("expr")

···

       19
        
               for p in opt.findall('attr[@name="loc"]/list/string')

     

       20
        
           ]

     

       21
        
       

     

       0
        
       
     

       22
        
       options.sort(key=sortKey)

     

       23
        
       

     

       24
        
       doc = ET.Element("expr")