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

refactor rendering command documentation to markdown
This commit is contained in:
Théophane Hufschmitt 2022-10-03 15:50:17 +02:00 committed by GitHub
commit 3ae9467d57
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 122 additions and 83 deletions

View file

@ -5,93 +5,106 @@ with import ./utils.nix;
let let
showCommand = showCommand = { command, details, filename }:
{ command, def, filename }:
''
**Warning**: This program is **experimental** and its interface is subject to change.
''
+ "# Name\n\n"
+ "`${command}` - ${def.description}\n\n"
+ "# Synopsis\n\n"
+ showSynopsis { inherit command; args = def.args; }
+ (if def.commands or {} != {}
then
let let
categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands))); result = ''
listCommands = cmds: > **Warning** \
concatStrings (map (name: > This program is **experimental** and its interface is subject to change.
"* "
+ "[`${command} ${name}`](./${appendName filename name}.md)" # Name
+ " - ${cmds.${name}.description}\n")
(attrNames cmds)); `${command}` - ${details.description}
in
"where *subcommand* is one of the following:\n\n" # Synopsis
# FIXME: group by category
+ (if length categories > 1 ${showSynopsis command details.args}
then
concatStrings (map ${maybeSubcommands}
(cat:
"**${toString cat.description}:**\n\n" ${maybeDocumentation}
+ listCommands (filterAttrs (n: v: v.category == cat) def.commands)
+ "\n" ${maybeOptions}
) categories) '';
+ "\n" showSynopsis = command: args:
else let
listCommands def.commands showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
+ "\n") arguments = concatStringsSep " " (map showArgument args);
else "") in ''
+ (if def ? doc `${command}` [*option*...] ${arguments}
then def.doc + "\n\n" '';
else "") maybeSubcommands = if details ? commands && details.commands != {}
+ (let s = showOptions def.flags; in then ''
if s != "" where *subcommand* is one of the following:
then "# Options\n\n${s}"
else "") ${subcommands}
; ''
else "";
subcommands = if length categories > 1
then listCategories
else listSubcommands details.commands;
categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
listCategories = concatStrings (map showCategory categories);
showCategory = cat: ''
**${toString cat.description}:**
${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; appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
showOptions = flags: processCommand = { command, details, filename }:
let 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; }

View file

@ -5,6 +5,32 @@ rec {
concatStrings = concatStringsSep ""; 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) # FIXME: O(n^2)
unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) []; unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) [];