Group subcommands by category

doc/manual/generate-manpage.nix

@@ -13,12 +13,27 @@ let
     + showSynopsis { inherit command; args = def.args; }
     + (if def.commands or {} != {}
        then
+         let
+           categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands)));
+           listCommands = cmds:
+             concatStrings (map (name:
+               "* [`${command} ${name}`](./${appendName filename name}.md) - ${cmds.${name}.description}\n")
+               (attrNames cmds));
+         in
          "where *subcommand* is one of the following:\n\n"
          # FIXME: group by category
-         + concatStrings (map (name:
+         + (if length categories > 1
-           "* [`${command} ${name}`](./${appendName filename name}.md) - ${def.commands.${name}.description}\n")
+            then
-           (attrNames def.commands))
+              concatStrings (map
+                (cat:
+                  "**${toString cat.description}:**\n\n"
+                  + listCommands (filterAttrs (n: v: v.category == cat) def.commands)
                   + "\n"
+                ) categories)
+              + "\n"
+            else
+              listCommands def.commands
+              + "\n")
        else "")
     + (if def ? doc
        then def.doc + "\n\n"

doc/manual/utils.nix

@@ -1,7 +1,15 @@
 with builtins;
 
-{
+rec {
   splitLines = s: filter (x: !isList x) (split "\n" s);
 
   concatStrings = concatStringsSep "";
+
+  # FIXME: O(n^2)
+  unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) [];
+
+  nameValuePair = name: value: { inherit name value; };
+
+  filterAttrs = pred: set:
+    listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set));
 }

src/libutil/args.cc

@@ -341,7 +341,10 @@ nlohmann::json MultiCommand::toJSON()
     for (auto & [name, commandFun] : commands) {
         auto command = commandFun();
         auto j = command->toJSON();
-        j["category"] = categories[command->category()];
+        auto cat = nlohmann::json::object();
+        cat["id"] = command->category();
+        cat["description"] = categories[command->category()];
+        j["category"] = std::move(cat);
         cmds[name] = std::move(j);
     }