Generate manpages for subcommands

[canac]

Maybe I'm missing something, but clap_mangen only seems to generate a manpage for the root command. I wanted additional manpages for each of the subcommands, like how git has manpages for git-status, git-checkout, etc. Here's the code I used to recursively generate those manpages, in case that's helpful to someone. It would be nice though if this were natively available in clap_mangen at some point because this is something that it seems like most projects would need.

// Generate man pages for this command and all of its subcommands
fn gen_manpage_recursive(cmd: clap::Command, out_dir: &Path) -> io::Result<()> {
    let name = String::from(cmd.get_name());
    let mut buffer: Vec<u8> = Default::default();
    clap_mangen::Man::new(cmd.clone()).render(&mut buffer)?;
    std::fs::write(out_dir.join(format!("{}.1", name)), buffer)?;

    for subcommand in cmd.get_subcommands() {
        let subcommand_name = subcommand.get_name();
        gen_manpage_recursive(
            subcommand
                .clone()
                .name(format!("{}-{}", name, subcommand_name)),
            out_dir,
        )?;
    }

    Ok(())
}

I'm kind of new to Rust, so there might be improvements that could be made.

[epage]

This isn't the smoothest yet as both our man page generation is weak and it is using an under-developed part of the API.

You need to at least use a private part of the API, cmd._build_all(); before this function (ie don't do it recursively). This will initialize the subcommands with their parent command names.

[canac]

Thanks for the tip!

[dnaka91]

Just stumbled upon this same problem. It seems by now the hidden cmd._build_all() function is available as cmd.build(). But I noticed that clap_mangen is not using the right naming for subcommands, when having nested subcommands.

This is how I generate the man pages currently:

fn print_manpages(dir: &Path) -> Result<()> {
    fn print(dir: &Path, app: &App) -> Result<()> {
        // `get_display_name()` is `Some` for all instances, except the root.
        let name = app.get_display_name().unwrap_or_else(|| app.get_name());
        let mut out = File::create(dir.join(format!("{name}.1")))?;

        clap_mangen::Man::new(app.clone()).render(&mut out)?;
        out.flush()?;

        for sub in app.get_subcommands() {
            print(dir, sub)?;
        }

        Ok(())
    }

    let mut app = Opt::command();
    app.build();

    print(dir, &app)
}

When having subcommands setup up like the following, it'll lose the information of the uppermost command (well, pretty much everything from the parent-parent name and upwards). Let's look at a simple example:

#[derive(Parser)]
#[clap(about, author, version)]
struct Opt {
    #[clap(subcommand)]
    cmd: Option<Command>,
}

#[derive(Subcommand)]
enum Command {
    Check {
        file: PathBuf,
    },
    Manpages {
        dir: PathBuf,
    },
    #[clap(subcommand)]
    Temp(TempCommand),
}

#[derive(Subcommand)]
enum TempCommand {
    TestA,
    TestB,
}

This will result in the following commands as present in the -h CLI output and the same proper naming with the manpage generator code above (assuming the crate is named sample, and omitting automatic help subcommands):

• sample
• sample-check
• sample-manpages
• sample-temp
• sample-temp-test-a
• sample-temp-test-b

But the clap_mangen generated content lists the following names in the SUBCOMMANDS section:

• sample-check(1)
• sample-manpages(1)
• sample-temp(1)
• temp-test-a(1) <-- missing sample- prefix
• temp-test-b(1) <-- missing sample- prefix

Is there currently a way to get around this? Had a quick peek at the code, and it seems not? The issue seems to be, that the generator uses get_name instead of get_display_name.

Also, should I open a separate issue ticket for this @epage?

[epage]

Also, should I open a separate issue ticket for this @epage?

Separate one, please. And it seems like it'd make sense to update clap_mangen to use get_display_name

[canac]

@dnaka91 Do you mind posting the link to that issue here when you create it so that I can subscribe to it for updates?

[dnaka91]

Sorry for the delay. Created an issue now: #4231

[igor-petruk]

Another issue with the suggested approach changing name in the first comment is that generated SYNOPSIS still used get_name(). While appropriated in other places, it causes subcommands usage examples have undesired dashes, e.g. cmd-sub1-sub2 where the user should call cmd sub1 sub2.

I am making this comment here as this approach was suggested for example as a correct solution here: #3629 (comment)