kubenix/docs/default.nix

# adapted from: https://discourse.nixos.org/t/franken-script-to-generate-nixos-options-docs-with-custom-modules/1674/4
{ pkgs, options }:
let
  extraSources = [ ];
  lib = pkgs.lib;

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

  # Replace functions by the string <function>
  substFunction = x:
    if builtins.isAttrs x
    then lib.mapAttrs (name: substFunction) x
    else if builtins.isList x
    then map substFunction x
    else if lib.isFunction x
    then "<function>"
    else if isPath x
    then toString x
    else x;

  isPath = x: (builtins.typeOf x) == "path";

  optionsListDesc = lib.flip map optionsListVisible (opt:
    opt // {
      description =
        let
          attempt = builtins.tryEval opt.description;
        in
        if attempt.success
        then attempt.value
        else "N/A";
      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 ? relatedPackages && opt.relatedPackages != [ ]) {
      relatedPackages = genRelatedPackages opt.relatedPackages;
    }
  );

  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
          title = args.title or null;
          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
        "<listitem>"
        + "<para><literal>${lib.optionalString (title != null)
        "${title} aka "}pkgs.${name} (${package.meta.name})</literal>"
        + lib.optionalString (!package.meta.available)
          " <emphasis>[UNAVAILABLE]</emphasis>"
        + ": ${package.meta.description or "???"}.</para>"
        + lib.optionalString (args ? comment)
          "\n<para>${args.comment}</para>"
        + lib.optionalString (package.meta ? longDescription)
          "\n<programlisting>${package.meta.longDescription}"
        + "</programlisting>"
        + "</listitem>";
    in
    "<itemizedlist>${lib.concatStringsSep "\n" (map (p:
    describe (unpack p))
  packages)}</itemizedlist>";

  optionLess = a: b:
    let
      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 a.loc b.loc < 0;

  prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources);
  stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip;

  ###############################################################################

  # This is the REAL meat of what we were after.
  # Output this however you want.
  optionsList = lib.sort optionLess optionsListDesc;

  optionsJSON = builtins.unsafeDiscardStringContext (builtins.toJSON
    (builtins.listToAttrs (map
      (o: {
        name = o.name;
        value = removeAttrs o [
          # Select the fields you want to drop here:
          "name"
          "visible"
          "internal"
          "loc"
          "readOnly"
        ];
      })
      optionsList)));
in
pkgs.writeText "options.json" optionsJSON