emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

feat(cli): allow docs to use %c/%p format specs

Browse source 
And replace magic section SYNOPSIS with EXAMPLES.
This commit is contained in:
Henrik Lissner 2022-06-21 02:08:19 +02:00
parent 0511445339
commit b0b727824a
No known key found for this signature in database
GPG key ID: B60957CA074D39A3
2 changed files with 27 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

14
core/cli/help.el
View file

@ -207,7 +207,7 @@ OPTIONS:
;; FIXME Who am I fooling?
(format (format "%%-%ds%%s%%%ds" width width)
"DOOM(1)" title "DOOM(1)")))
("NAME" . ,(concat (doom-cli-command-string cli) " - " .summary))
("NAME" . ,(concat .command " - " .summary))
("SYNOPSIS" . ,(doom-cli-help--render-synopsis .synopsis nil t))
("DESCRIPTION" . ,.description))
`((nil . ,(doom-cli-help--render-synopsis .synopsis "Usage: "))
@ -222,9 +222,17 @@ OPTIONS:
(if (or (not (doom-cli-fn cli)) noglobal?)
`(,(assq 'local .options))
.options)
cli)))))
cli))))
(command (doom-cli-command cli)))
(letf! (defun printsection (section)
(print! "%s\n" (if section (markup section) (dark "TODO"))))
(print! "%s\n"
(if (null section)
(dark "TODO")
(markup
(format-spec
section `((?p . ,(car command))
(?c . ,(doom-cli-command-string (cdr command))))
'ignore)))))
(pcase-dolist (`(,label . ,contents) alist)
(when (and contents (not (string-blank-p contents)))
(when label

22
core/core-cli-lib.el
View file

@ -1280,23 +1280,33 @@ command listings served by help commands. The rest of DOCSTRING lines should be
no longer than 80 columns, and should go into greater detail. This documentation
may use `quoting' to appropriately highlight ARGUMENTS, --options, or $ENVVARS.
DOCSTRING may also contain sections, denoted by a capitalized header ending with
DOCSTRING may also contain sections denoted by a capitalized header ending with
a colon and newline, and its contents indented by 2 spaces. These will be
appended to the end of the help documentation for that command. These three
sections are special:
SYNOPSIS:
These are appended to the pregenerated SYNOPSIS of any commands help
documentation. Use this to specify additional use cases and examples for the
command.
ARGUMENTS:
Use this to specify longer-form documentation for arguments. They are
appended to the auto-generated section of the same name.
prepended to the documentation for commands. If pseudo CLIs specify their
own ARGUMENTS sections, they are joined with that of the root command's CLI
as well. E.g. ':before doom sync's ARGUMENTS will be prepended to 'doom
sync's.
OPTIONS:
Use this to specify longer-form documentation for options. They are appended
to the auto-generated section of the same name. Only the option needs to be
specified for its lookup behavior to work. See bin/doom's `doom' command as
an example.
EXAMPLES:
To list example uses of the containing script. These are appended to
SYNOPSIS in generated manpages, but treated as a normal section otherwise
(i.e. appended to 'doom help's output).
DOCSTRING may use any of these format specifications:
%p The running script's prefix. E.g. for 'doom ci deploy-hooks' the
prefix is 'doom'.
%c The parent command minus the prefix. E.g. for 'doom ci deploy-hooks',
the command is 'ci deploy-hooks'.
ARGLIST is a specification for options and arguments that is accepted by this
command. Arguments are represented by either a symbol or a cons cell where