Merge pull request #6969 from fricklerhandwerk/refactor-generate-manpage
refactor rendering command documentation to markdown
This commit is contained in:
Théophane Hufschmitt
GitHub
commit
3ae9467d57
2 changed files with 122 additions and 83 deletions
|
|
@ -5,93 +5,106 @@ with import ./utils.nix;
|
||||||
|
|
||||||
let
|
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;
|
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; }
|
|
||||||
|
|
|
||||||
|
|
@ -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 ]) [];
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue