it's a really simple library inspired by clap-help but with support for submodules, and custom Markdown guides. it prints your clap help as markdown with a bit of color and will open a scrollable view if the output doesn't fit on screen.
help_command/help_command_docsand friends plug straight into your clap match armsHelpArgsis a clapArgsstruct you can attach to your ownhelpcommandDocRegistry+CommandDocstore extra blurbs, examples, notes, and guides keyed by dot-separated paths (""points to the program itself)HelpThemewraps atermimad::MadSkinwith an accent colorHelpPage,render_command_help, andrun_scrollable_helplet you render things yourself if you want something lower-level
you have two main ways of using this library, and you can do them at the same time!
you can add a snippet like this to your clap command matching (using HelpArgs):
Some(Commands::Help(args)) =>
{
chkc_help::help_command(
"My Cool Project",
Some(env!("CARGO_PKG_VERSION")),
&Cli::command(),
&theme,
&args
)
},where args comes from
use chkc_help::{Color, HelpArgs, HelpTheme};you can add this to your command matching:
None => {
chkc_help::help_command_program(
"My Cool Project",
Some(env!("CARGO_PKG_VERSION")),
&Cli::command(),
&theme
)?;
Ok(())
}both help_command and help_command_program have a _docs variant that additionally takes
in a DocRegistry, which you can create by doing so before parsing:
let mut docs = chkc_help::DocRegistry::new();you can then register commands or guides by doing docs.register_command(key, cmd)
and docs.register_guide(key, guide) respectively. the key is a value referring to the
"namespace" or command, which should be separated by dots in the case of subcommands
(e.g: git.commit)
having a doc registry is really recommended, because you can add a description (leave empty to use the one extracted from doc comments), examples of your command usage, and even notes.
for example:
registry.register_command(
"commit",
CommandDoc::new(
"Create a new commit containing the current contents of the index and
the given log message describing the changes.",
[
"Commit a repository: `git -m ~~'commit message'~~`",
],
["If you make a commit and then find a mistake immediately after that, you can recover from it with git reset."],
),
);note that an empty key in the doc registry symbolizes the
main program itself, so program help guide is still
valid
oh, well too bad. just kidding, you can use the lower level
run_help_topic(app_name, app_version, root, &docs, theme, &topic)where topic is a Vec<String>
CommandDoc::new(desc, examples, notes)will drop an empty description and keep your clap doc comments insteadregister_command("foo.bar", doc)attaches data to a subcommandregister_guide("git.rebase", include_str!("docs/rebase.md"))stashes arbitrary markdown you can open withhelp git rebase guide- pass the registry to the
_docshelpers to make it all show up
- "Usage:" is trimmed off clap's output, leaving just the syntax in backticks
- subcommands and options are printed as small tables; strikethrough text uses the accent color
(better than squinting at a
strikethat doesn't render everywhere) - if the markdown has more lines than the terminal, you'll get a scrollable view with arrows,
page up/down, and
q/escto quit
you've probably seen &theme around, but what is it? well, it's simple.
you create it like this:
use chkc_help::{Color, HelpTheme, /* other imports */};
// in your main function
let theme = HelpTheme::default(Color::Blue);you can specify your accent color of your choice, of course. HelpTheme::light, dark and
new all exist too, with the latter taking a mut skin: MadSkin in case you want some more
customization. the accent color will still override some stuff though. if you want to render
the markdown yourself, render_command_help and run_scrollable_help are exported as well.
alright thats all, bye