@ -15,13 +15,43 @@ let
else if lib . isFunction x then " < f u n c t i o n > "
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 " I n v a l i d p a c k a g e a t t r i b u t e p a t h ` ${ toString path } ' " ) pkgs ) ;
in " < l i s t i t e m > "
+ " < p a r a > < l i t e r a l > p k g s . ${ name } ( ${ package . meta . name } ) < / l i t e r a l > "
+ lib . optionalString ( ! package . meta . evaluates ) " < e m p h a s i s > [ U N A V A I L A B L E ] < / e m p h a s i s > "
+ " : ${ package . meta . description or " ? ? ? " } . < / p a r a > "
+ lib . optionalString ( args ? comment ) " \n < p a r a > ${ args . comment } < / p a r a > "
# Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>
+ lib . optionalString ( package . meta ? longDescription ) " \n < p r o g r a m l i s t i n g > ${ package . meta . longDescription } < / p r o g r a m l i s t i n g > "
+ " < / l i s t i t e m > " ;
in " < i t e m i z e d l i s t > ${ lib . concatStringsSep " \n " ( map ( p : describe ( unpack p ) ) packages ) } < / i t e m i z e d l i s t > " ;
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,