chkc's help

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.

what ships in the crate?

• help_command / help_command_docs and friends plug straight into your clap match arms
• HelpArgs is a clap Args struct you can attach to your own help command
• DocRegistry + CommandDoc store extra blurbs, examples, notes, and guides keyed by dot-separated paths ("" points to the program itself)
• HelpTheme wraps a termimad::MadSkin with an accent color
• HelpPage, render_command_help, and run_scrollable_help let you render things yourself if you want something lower-level

how do i use it?

you have two main ways of using this library, and you can do them at the same time!

specific help command

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};

help when no command specified

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(())
        }

help + markdown guides (additional command data)

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

but i dont want to use HelpArgs!

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>

docs registry cheat sheet

• CommandDoc::new(desc, examples, notes) will drop an empty description and keep your clap doc comments instead
• register_command("foo.bar", doc) attaches data to a subcommand
• register_guide("git.rebase", include_str!("docs/rebase.md")) stashes arbitrary markdown you can open with help git rebase guide
• pass the registry to the _docs helpers to make it all show up

rendering bits

• "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 strike that 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 / esc to quit

theming

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