refactor rendering command documentation to markdown

idea:
- make document structure visible, like in a template
- order functions by descending abstraction
- avoid nested let bindings
This commit is contained in:
Valentin Gagarin 2022-08-26 17:40:34 +02:00
parent 6b56bb4a79
commit 4655563470

View file

@ -5,10 +5,70 @@ with import ./utils.nix;
let let
showCommand = showCommand = { command, def, filename }:
{ command, def, filename }: let
'' showSynopsis = command: args:
> **Warning** let
showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
arguments = concatStringsSep " " (map showArgument args);
in ''
`${command}` [*option*...] ${arguments}
'';
maybeSubcommands = if def ? commands && def.commands != {}
then ''
where *subcommand* is one of the following:
${subcommands}
''
else "";
subcommands = if length categories > 1
then listCategories
else listSubcommands def.commands;
categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands)));
listCategories = concatStrings (map showCategory categories);
showCategory = cat: ''
**${toString cat.description}:**
${listSubcommands (filterAttrs (n: v: v.category == cat) def.commands)}
'';
listSubcommands = cmds: concatStrings (attrValues (mapAttrs showSubcommand cmds));
showSubcommand = name: subcmd: ''
* [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
'';
maybeDocumentation = if def ? doc then def.doc else "";
maybeOptions = if def.flags == {} then "" else ''
# Options
${showOptions def.flags}
'';
showOptions = flags:
let
categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags)));
in
concatStrings (map
(cat:
(if cat != ""
then "**${cat}:**\n\n"
else "")
+ concatStrings
(map (longName:
let
flag = flags.${longName};
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);
squash = string: # squash more than two repeated newlines
let
replaced = replaceStrings [ "\n\n\n" ] [ "\n\n" ] string;
in
if replaced == string then string else squash replaced;
in squash ''
> **Warning** \
> This program is **experimental** and its interface is subject to change. > This program is **experimental** and its interface is subject to change.
# Name # Name
@ -17,75 +77,17 @@ let
# Synopsis # Synopsis
${showSynopsis { inherit command; args = def.args; }} ${showSynopsis command def.args}
'' ${maybeSubcommands}
+ (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:
'' ${maybeDocumentation}
# FIXME: group by category
+ (if length categories > 1 ${maybeOptions}
then '';
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"
else "")
+ (let s = showOptions def.flags; in
if s != ""
then "# Options\n\n${s}"
else "")
;
appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name; appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
showOptions = flags:
let
categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags)));
in
concatStrings (map
(cat:
(if cat != ""
then "**${cat}:**\n\n"
else "")
+ concatStrings
(map (longName:
let
flag = flags.${longName};
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 =
{ command, args }:
"`${command}` [*option*...] ${concatStringsSep " "
(map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}";
processCommand = { command, def, filename }: processCommand = { command, def, filename }:
[ { name = filename + ".md"; value = showCommand { inherit command def filename; }; inherit command; } ] [ { name = filename + ".md"; value = showCommand { inherit command def filename; }; inherit command; } ]
++ concatMap ++ concatMap