Merge pull request #6969 from fricklerhandwerk/refactor-generate-manpage

refactor rendering command documentation to markdown

doc/manual/generate-manpage.nix

@@ -5,93 +5,106 @@ with import ./utils.nix;
 
 let
 
-  showCommand =
+  showCommand = { command, details, filename }:
-    { command, def, filename }:
+    let
-    ''
+      result = ''
-      **Warning**: This program is **experimental** and its interface is subject to change.
+        > **Warning** \
-    ''
+        > This program is **experimental** and its interface is subject to change.
-    + "# Name\n\n"
+
-    + "`${command}` - ${def.description}\n\n"
+        # Name
-    + "# Synopsis\n\n"
+
-    + showSynopsis { inherit command; args = def.args; }
+        `${command}` - ${details.description}
-    + (if def.commands or {} != {}
+
-       then
+        # Synopsis
-         let
+
-           categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands)));
+        ${showSynopsis command details.args}
-           listCommands = cmds:
+
-             concatStrings (map (name:
+        ${maybeSubcommands}
-               "* "
+
-               + "[`${command} ${name}`](./${appendName filename name}.md)"
+        ${maybeDocumentation}
-               + " - ${cmds.${name}.description}\n")
+
-               (attrNames cmds));
+        ${maybeOptions}
-         in
+      '';
-         "where *subcommand* is one of the following:\n\n"
+      showSynopsis = command: args:
-         # FIXME: group by category
+        let
-         + (if length categories > 1
+          showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
-            then
+          arguments = concatStringsSep " " (map showArgument args);
-              concatStrings (map
+        in ''
-                (cat:
+         `${command}` [*option*...] ${arguments}
-                  "**${toString cat.description}:**\n\n"
+        '';
-                  + listCommands (filterAttrs (n: v: v.category == cat) def.commands)
+      maybeSubcommands = if details ? commands && details.commands != {}
-                  + "\n"
+        then ''
-                ) categories)
+           where *subcommand* is one of the following:
-              + "\n"
+
-            else
+           ${subcommands}
-              listCommands def.commands
+         ''
-              + "\n")
+        else "";
-       else "")
+      subcommands = if length categories > 1
-    + (if def ? doc
+        then listCategories
-       then def.doc + "\n\n"
+        else listSubcommands details.commands;
-       else "")
+      categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
-    + (let s = showOptions def.flags; in
+      listCategories = concatStrings (map showCategory categories);
-       if s != ""
+      showCategory = cat: ''
-       then "# Options\n\n${s}"
+        **${toString cat.description}:**
-       else "")
+
-  ;
+        ${listSubcommands (filterAttrs (n: v: v.category == cat) details.commands)}
+      '';
+      listSubcommands = cmds: concatStrings (attrValues (mapAttrs showSubcommand cmds));
+      showSubcommand = name: subcmd: ''
+        * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
+      '';
+      maybeDocumentation = if details ? doc then details.doc else "";
+      maybeOptions = if details.flags == {} then "" else ''
+        # Options
+
+        ${showOptions details.flags}
+      '';
+      showOptions = options:
+        let
+          showCategory = cat: ''
+            ${if cat != "" then "**${cat}:**" else ""}
+
+            ${listOptions (filterAttrs (n: v: v.category == cat) options)}
+            '';
+          listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts));
+          showOption = name: option:
+            let
+              shortName = if option ? shortName then "/ `-${option.shortName}`" else "";
+              labels = if option ? labels then (concatStringsSep " " (map (s: "*${s}*") option.labels)) else "";
+            in trim ''
+              - `--${name}` ${shortName} ${labels}
+
+                ${option.description}
+            '';
+          categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues options)));
+        in concatStrings (map showCategory categories);
+    in squash result;
 
   appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
 
-  showOptions = flags:
+  processCommand = { command, details, filename }:
     let
-      categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags)));
+      cmd = {
-    in
+        inherit command;
-      concatStrings (map
+        name = filename + ".md";
-        (cat:
+        value = showCommand { inherit command details filename; };
-          (if cat != ""
+      };
-           then "**${cat}:**\n\n"
+      subcommand = subCmd: processCommand {
-           else "")
+        command = command + " " + subCmd;
-          + concatStrings
+        details = details.commands.${subCmd};
-            (map (longName:
+        filename = appendName filename subCmd;
-              let
+      };
-                flag = flags.${longName};
+    in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
-              in
-                "  - `--${longName}`"
-                + (if flag ? shortName then " / `-${flag.shortName}`" else "")
-                + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "")
-                + "  \n"
-                + "    " + flag.description + "\n\n"
-            ) (attrNames (filterAttrs (n: v: v.category == cat) flags))))
-        categories);
 
-  showSynopsis =
+  manpages = processCommand {
-    { command, args }:
+    command = "nix";
-    "`${command}` [*option*...] ${concatStringsSep " "
+    details = builtins.fromJSON command;
-      (map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}\n\n";
+    filename = "nix";
+  };
 
-  processCommand = { command, def, filename }:
+  tableOfContents = let
-    [ { name = filename + ".md"; value = showCommand { inherit command def filename; }; inherit command; } ]
+    showEntry = page:
-    ++ concatMap
+      "    - [${page.command}](command-ref/new-cli/${page.name})";
-      (name: processCommand {
+    in concatStringsSep "\n" (map showEntry manpages) + "\n";
-        filename = appendName filename name;
-        command = command + " " + name;
-        def = def.commands.${name};
-      })
-      (attrNames def.commands or {});
 
-in
+in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
-
-let
-  manpages = processCommand { filename = "nix"; command = "nix"; def = builtins.fromJSON command; };
-  summary = concatStrings (map (manpage: "    - [${manpage.command}](command-ref/new-cli/${manpage.name})\n") manpages);
-in
-(listToAttrs manpages) // { "SUMMARY.md" = summary; }

doc/manual/utils.nix

@@ -5,6 +5,32 @@ rec {
 
   concatStrings = concatStringsSep "";
 
+  replaceStringsRec = from: to: string:
+    # recursively replace occurrences of `from` with `to` within `string`
+    # example:
+    #     replaceStringRec "--" "-" "hello-----world"
+    #     => "hello-world"
+    let
+      replaced = replaceStrings [ from ] [ to ] string;
+    in
+      if replaced == string then string else replaceStringsRec from to replaced;
+
+  squash = replaceStringsRec "\n\n\n" "\n\n";
+
+  trim = string:
+    # trim trailing spaces and squash non-leading spaces
+    let
+      trimLine = line:
+        let
+          # separate leading spaces from the rest
+          parts = split "(^ *)" line;
+          spaces = head (elemAt parts 1);
+          rest = elemAt parts 2;
+          # drop trailing spaces
+          body = head (split " *$" rest);
+        in spaces + replaceStringsRec "  " " " body;
+    in concatStringsSep "\n" (map trimLine (splitLines string));
+
   # FIXME: O(n^2)
   unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) [];