From 3e0bb1eb297384fe5d090135c7dd855cdc592828 Mon Sep 17 00:00:00 2001 From: Yihuang Yu Date: Fri, 17 May 2024 12:06:35 +0800 Subject: [PATCH 1/3] docs: Set bin_name for subcommands and use full title `bin_name` will be displayed in the `SYNOPSIS` section, with this, the generated man pages have correct name and synopsis. Also, remove `.title("bootc")` to let the subcommands have their own titles. Signed-off-by: Yihuang Yu --- docs/src/man/bootc-edit.md | 2 +- docs/src/man/bootc-install-print-configuration.md | 2 +- docs/src/man/bootc-install-to-disk.md | 2 +- docs/src/man/bootc-install-to-existing-root.md | 2 +- docs/src/man/bootc-install-to-filesystem.md | 2 +- docs/src/man/bootc-install.md | 2 +- docs/src/man/bootc-rollback.md | 2 +- docs/src/man/bootc-status.md | 2 +- docs/src/man/bootc-switch.md | 2 +- docs/src/man/bootc-upgrade.md | 2 +- docs/src/man/bootc-usr-overlay.md | 2 +- lib/src/docgen.rs | 11 +++++++++-- 12 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/src/man/bootc-edit.md b/docs/src/man/bootc-edit.md index c5e78f1d..2dd8c570 100644 --- a/docs/src/man/bootc-edit.md +++ b/docs/src/man/bootc-edit.md @@ -4,7 +4,7 @@ bootc-edit - Apply full changes to the host specification # SYNOPSIS -**bootc-edit** \[**-f**\|**\--filename**\] \[**\--quiet**\] +**bootc edit** \[**-f**\|**\--filename**\] \[**\--quiet**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] # DESCRIPTION diff --git a/docs/src/man/bootc-install-print-configuration.md b/docs/src/man/bootc-install-print-configuration.md index f74ce376..9ba06d66 100644 --- a/docs/src/man/bootc-install-print-configuration.md +++ b/docs/src/man/bootc-install-print-configuration.md @@ -7,7 +7,7 @@ processes using \`install to-filesystem\` that want to honor e.g. # SYNOPSIS -**bootc-install-print-configuration** \[**-h**\|**\--help**\] +**bootc install print-configuration** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] # DESCRIPTION diff --git a/docs/src/man/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md index e897be26..c68080aa 100644 --- a/docs/src/man/bootc-install-to-disk.md +++ b/docs/src/man/bootc-install-to-disk.md @@ -4,7 +4,7 @@ bootc-install-to-disk - Install to the target block device # SYNOPSIS -**bootc-install-to-disk** \[**\--wipe**\] \[**\--block-setup**\] +**bootc install to-disk** \[**\--wipe**\] \[**\--block-setup**\] \[**\--filesystem**\] \[**\--root-size**\] \[**\--source-imgref**\] \[**\--target-transport**\] \[**\--target-imgref**\] \[**\--enforce-container-sigpolicy**\] \[**\--target-ostree-remote**\] diff --git a/docs/src/man/bootc-install-to-existing-root.md b/docs/src/man/bootc-install-to-existing-root.md index 8eb3e961..0dbb2b34 100644 --- a/docs/src/man/bootc-install-to-existing-root.md +++ b/docs/src/man/bootc-install-to-existing-root.md @@ -5,7 +5,7 @@ root filesystem # SYNOPSIS -**bootc-install-to-existing-root** \[**\--replace**\] +**bootc install to-existing-root** \[**\--replace**\] \[**\--source-imgref**\] \[**\--target-transport**\] \[**\--target-imgref**\] \[**\--enforce-container-sigpolicy**\] \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] diff --git a/docs/src/man/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md index 63a811d7..63c290eb 100644 --- a/docs/src/man/bootc-install-to-filesystem.md +++ b/docs/src/man/bootc-install-to-filesystem.md @@ -4,7 +4,7 @@ bootc-install-to-filesystem - Install to the target filesystem # SYNOPSIS -**bootc-install-to-filesystem** \[**\--root-mount-spec**\] +**bootc install to-filesystem** \[**\--root-mount-spec**\] \[**\--boot-mount-spec**\] \[**\--replace**\] \[**\--acknowledge-destructive**\] \[**\--skip-finalize**\] \[**\--source-imgref**\] \[**\--target-transport**\] diff --git a/docs/src/man/bootc-install.md b/docs/src/man/bootc-install.md index 5ecba35f..32f04231 100644 --- a/docs/src/man/bootc-install.md +++ b/docs/src/man/bootc-install.md @@ -4,7 +4,7 @@ bootc-install - Install the running container to a target # SYNOPSIS -**bootc-install** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +**bootc install** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*subcommands*\> # DESCRIPTION diff --git a/docs/src/man/bootc-rollback.md b/docs/src/man/bootc-rollback.md index 3e81dbf2..8454970a 100644 --- a/docs/src/man/bootc-rollback.md +++ b/docs/src/man/bootc-rollback.md @@ -7,7 +7,7 @@ queued upgrade) then it will be discarded # SYNOPSIS -**bootc-rollback** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +**bootc rollback** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] # DESCRIPTION diff --git a/docs/src/man/bootc-status.md b/docs/src/man/bootc-status.md index 13ff1b6d..4af82885 100644 --- a/docs/src/man/bootc-status.md +++ b/docs/src/man/bootc-status.md @@ -4,7 +4,7 @@ bootc-status - Display status # SYNOPSIS -**bootc-status** \[**\--json**\] \[**\--booted**\] +**bootc status** \[**\--json**\] \[**\--booted**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] # DESCRIPTION diff --git a/docs/src/man/bootc-switch.md b/docs/src/man/bootc-switch.md index 8935af25..dd1283bc 100644 --- a/docs/src/man/bootc-switch.md +++ b/docs/src/man/bootc-switch.md @@ -4,7 +4,7 @@ bootc-switch - Target a new container image reference to boot # SYNOPSIS -**bootc-switch** \[**\--quiet**\] \[**\--transport**\] +**bootc switch** \[**\--quiet**\] \[**\--transport**\] \[**\--enforce-container-sigpolicy**\] \[**\--ostree-remote**\] \[**\--retain**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*TARGET*\> diff --git a/docs/src/man/bootc-upgrade.md b/docs/src/man/bootc-upgrade.md index bdb09f18..fd0c3430 100644 --- a/docs/src/man/bootc-upgrade.md +++ b/docs/src/man/bootc-upgrade.md @@ -4,7 +4,7 @@ bootc-upgrade - Download and queue an updated container image to apply # SYNOPSIS -**bootc-upgrade** \[**\--quiet**\] \[**\--check**\] \[**\--apply**\] +**bootc upgrade** \[**\--quiet**\] \[**\--check**\] \[**\--apply**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] # DESCRIPTION diff --git a/docs/src/man/bootc-usr-overlay.md b/docs/src/man/bootc-usr-overlay.md index 6a0b5bdd..055864ad 100644 --- a/docs/src/man/bootc-usr-overlay.md +++ b/docs/src/man/bootc-usr-overlay.md @@ -5,7 +5,7 @@ will be discarded on reboot # SYNOPSIS -**bootc-usr-overlay** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +**bootc usr-overlay** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] # DESCRIPTION diff --git a/lib/src/docgen.rs b/lib/src/docgen.rs index f29d4aef..22beac8a 100644 --- a/lib/src/docgen.rs +++ b/lib/src/docgen.rs @@ -15,6 +15,8 @@ pub fn generate_manpages(directory: &Utf8Path) -> Result<()> { fn generate_one(directory: &Utf8Path, cmd: Command) -> Result<()> { let version = env!("CARGO_PKG_VERSION"); let name = cmd.get_name(); + let bin_name = cmd.get_bin_name() + .unwrap_or_else(|| name); let path = directory.join(format!("{name}.8")); println!("Generating {path}..."); @@ -26,7 +28,6 @@ fn generate_one(directory: &Utf8Path, cmd: Command) -> Result<()> { .with_context(|| format!("opening {path}")) .map(std::io::BufWriter::new)?; clap_mangen::Man::new(cmd.clone()) - .title("bootc") .section("8") .source(format!("bootc {version}")) .render(&mut out) @@ -36,10 +37,16 @@ fn generate_one(directory: &Utf8Path, cmd: Command) -> Result<()> { for subcmd in cmd.get_subcommands().filter(|c| !c.is_hide_set()) { let subname = format!("{}-{}", name, subcmd.get_name()); + let bin_name = format!("{} {}", bin_name, subcmd.get_name()); // SAFETY: Latest clap 4 requires names are &'static - this is // not long-running production code, so we just leak the names here. let subname = &*std::boxed::Box::leak(subname.into_boxed_str()); - let subcmd = subcmd.clone().name(subname).alias(subname).version(version); + let bin_name = &*std::boxed::Box::leak(bin_name.into_boxed_str()); + let subcmd = subcmd.clone() + .name(subname) + .alias(subname) + .bin_name(bin_name) + .version(version); generate_one(directory, subcmd.clone().name(subname).version(version))?; } Ok(()) From 867b8c847db79b5c6e6084cdfc762c5212ced6b6 Mon Sep 17 00:00:00 2001 From: Yihuang Yu Date: Fri, 17 May 2024 12:30:20 +0800 Subject: [PATCH 2/3] docs: Disable "version" option for subcommands Subcommands don't have their own versions, so disable the "version" option. Signed-off-by: Yihuang Yu --- docs/src/man/bootc-edit.md | 6 +----- docs/src/man/bootc-install-print-configuration.md | 5 ----- docs/src/man/bootc-install-to-disk.md | 7 +------ docs/src/man/bootc-install-to-existing-root.md | 6 +----- docs/src/man/bootc-install-to-filesystem.md | 6 +----- docs/src/man/bootc-install.md | 7 +------ docs/src/man/bootc-rollback.md | 6 +----- docs/src/man/bootc-status.md | 6 +----- docs/src/man/bootc-switch.md | 7 +------ docs/src/man/bootc-upgrade.md | 6 +----- docs/src/man/bootc-usr-overlay.md | 6 +----- lib/src/docgen.rs | 3 ++- 12 files changed, 12 insertions(+), 59 deletions(-) diff --git a/docs/src/man/bootc-edit.md b/docs/src/man/bootc-edit.md index 2dd8c570..2d2bb486 100644 --- a/docs/src/man/bootc-edit.md +++ b/docs/src/man/bootc-edit.md @@ -5,7 +5,7 @@ bootc-edit - Apply full changes to the host specification # SYNOPSIS **bootc edit** \[**-f**\|**\--filename**\] \[**\--quiet**\] -\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +\[**-h**\|**\--help**\] # DESCRIPTION @@ -34,10 +34,6 @@ Only changes to the \`spec\` section are honored. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # VERSION v0.1.11 diff --git a/docs/src/man/bootc-install-print-configuration.md b/docs/src/man/bootc-install-print-configuration.md index 9ba06d66..db6da67d 100644 --- a/docs/src/man/bootc-install-print-configuration.md +++ b/docs/src/man/bootc-install-print-configuration.md @@ -8,7 +8,6 @@ processes using \`install to-filesystem\` that want to honor e.g. # SYNOPSIS **bootc install print-configuration** \[**-h**\|**\--help**\] -\[**-V**\|**\--version**\] # DESCRIPTION @@ -25,10 +24,6 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # VERSION v0.1.11 diff --git a/docs/src/man/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md index c68080aa..05f75feb 100644 --- a/docs/src/man/bootc-install-to-disk.md +++ b/docs/src/man/bootc-install-to-disk.md @@ -10,8 +10,7 @@ bootc-install-to-disk - Install to the target block device \[**\--enforce-container-sigpolicy**\] \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] -\[**\--via-loopback**\] \[**-h**\|**\--help**\] -\[**-V**\|**\--version**\] \<*DEVICE*\> +\[**\--via-loopback**\] \[**-h**\|**\--help**\] \<*DEVICE*\> # DESCRIPTION @@ -128,10 +127,6 @@ firmware will be skipped : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - \<*DEVICE*\> : Target block device for installation. The entire device will be diff --git a/docs/src/man/bootc-install-to-existing-root.md b/docs/src/man/bootc-install-to-existing-root.md index 0dbb2b34..cf571a26 100644 --- a/docs/src/man/bootc-install-to-existing-root.md +++ b/docs/src/man/bootc-install-to-existing-root.md @@ -12,7 +12,7 @@ root filesystem \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] \[**\--acknowledge-destructive**\] \[**-h**\|**\--help**\] -\[**-V**\|**\--version**\] \[*ROOT_PATH*\] +\[*ROOT_PATH*\] # DESCRIPTION @@ -117,10 +117,6 @@ firmware will be skipped : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - \[*ROOT_PATH*\] \[default: /target\] : Path to the mounted root; its expected to invoke podman with \`-v diff --git a/docs/src/man/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md index 63c290eb..cf915b79 100644 --- a/docs/src/man/bootc-install-to-filesystem.md +++ b/docs/src/man/bootc-install-to-filesystem.md @@ -12,7 +12,7 @@ bootc-install-to-filesystem - Install to the target filesystem \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] -\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*ROOT_PATH*\> +\[**-h**\|**\--help**\] \<*ROOT_PATH*\> # DESCRIPTION @@ -140,10 +140,6 @@ firmware will be skipped : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - \<*ROOT_PATH*\> : Path to the mounted root filesystem. diff --git a/docs/src/man/bootc-install.md b/docs/src/man/bootc-install.md index 32f04231..03f71a6b 100644 --- a/docs/src/man/bootc-install.md +++ b/docs/src/man/bootc-install.md @@ -4,8 +4,7 @@ bootc-install - Install the running container to a target # SYNOPSIS -**bootc install** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] -\<*subcommands*\> +**bootc install** \[**-h**\|**\--help**\] \<*subcommands*\> # DESCRIPTION @@ -35,10 +34,6 @@ includes other setup and metadata. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # SUBCOMMANDS bootc-install-to-disk(8) diff --git a/docs/src/man/bootc-rollback.md b/docs/src/man/bootc-rollback.md index 8454970a..42bb5363 100644 --- a/docs/src/man/bootc-rollback.md +++ b/docs/src/man/bootc-rollback.md @@ -7,7 +7,7 @@ queued upgrade) then it will be discarded # SYNOPSIS -**bootc rollback** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +**bootc rollback** \[**-h**\|**\--help**\] # DESCRIPTION @@ -32,10 +32,6 @@ rollback invocation. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # VERSION v0.1.11 diff --git a/docs/src/man/bootc-status.md b/docs/src/man/bootc-status.md index 4af82885..3cc88e49 100644 --- a/docs/src/man/bootc-status.md +++ b/docs/src/man/bootc-status.md @@ -5,7 +5,7 @@ bootc-status - Display status # SYNOPSIS **bootc status** \[**\--json**\] \[**\--booted**\] -\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +\[**-h**\|**\--help**\] # DESCRIPTION @@ -31,10 +31,6 @@ The exact API format is not currently declared stable. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # VERSION v0.1.11 diff --git a/docs/src/man/bootc-switch.md b/docs/src/man/bootc-switch.md index dd1283bc..9f8a9070 100644 --- a/docs/src/man/bootc-switch.md +++ b/docs/src/man/bootc-switch.md @@ -6,8 +6,7 @@ bootc-switch - Target a new container image reference to boot **bootc switch** \[**\--quiet**\] \[**\--transport**\] \[**\--enforce-container-sigpolicy**\] \[**\--ostree-remote**\] -\[**\--retain**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] -\<*TARGET*\> +\[**\--retain**\] \[**-h**\|**\--help**\] \<*TARGET*\> # DESCRIPTION @@ -55,10 +54,6 @@ includes a default policy which requires signatures. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - \<*TARGET*\> : Target image to use for the next boot diff --git a/docs/src/man/bootc-upgrade.md b/docs/src/man/bootc-upgrade.md index fd0c3430..908d05f7 100644 --- a/docs/src/man/bootc-upgrade.md +++ b/docs/src/man/bootc-upgrade.md @@ -5,7 +5,7 @@ bootc-upgrade - Download and queue an updated container image to apply # SYNOPSIS **bootc upgrade** \[**\--quiet**\] \[**\--check**\] \[**\--apply**\] -\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +\[**-h**\|**\--help**\] # DESCRIPTION @@ -50,10 +50,6 @@ userspace-only restart. : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # VERSION v0.1.11 diff --git a/docs/src/man/bootc-usr-overlay.md b/docs/src/man/bootc-usr-overlay.md index 055864ad..07ac8cd2 100644 --- a/docs/src/man/bootc-usr-overlay.md +++ b/docs/src/man/bootc-usr-overlay.md @@ -5,7 +5,7 @@ will be discarded on reboot # SYNOPSIS -**bootc usr-overlay** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +**bootc usr-overlay** \[**-h**\|**\--help**\] # DESCRIPTION @@ -37,10 +37,6 @@ unmount\". : Print help (see a summary with -h) -**-V**, **\--version** - -: Print version - # VERSION v0.1.11 diff --git a/lib/src/docgen.rs b/lib/src/docgen.rs index 22beac8a..06ea39b2 100644 --- a/lib/src/docgen.rs +++ b/lib/src/docgen.rs @@ -46,7 +46,8 @@ fn generate_one(directory: &Utf8Path, cmd: Command) -> Result<()> { .name(subname) .alias(subname) .bin_name(bin_name) - .version(version); + .version(version) + .disable_version_flag(true); generate_one(directory, subcmd.clone().name(subname).version(version))?; } Ok(()) From 7df0b5861844806b73700fa0b0f49b411042fe00 Mon Sep 17 00:00:00 2001 From: Yihuang Yu Date: Fri, 17 May 2024 12:50:01 +0800 Subject: [PATCH 3/3] docs: Delete outdate docs/src/bootc.md Signed-off-by: Yihuang Yu --- docs/src/bootc.md | 57 ----------------------------------------------- 1 file changed, 57 deletions(-) delete mode 100644 docs/src/bootc.md diff --git a/docs/src/bootc.md b/docs/src/bootc.md deleted file mode 100644 index d8c313ea..00000000 --- a/docs/src/bootc.md +++ /dev/null @@ -1,57 +0,0 @@ -# NAME - -bootc - Deploy and transactionally in-place with bootable container -images - -# SYNOPSIS - -**bootc** \[**-h**\|**\--help**\] \<*subcommands*\> - -# DESCRIPTION - -Deploy and transactionally in-place with bootable container images. - -The \`bootc\` project currently uses ostree-containers as a backend to -support a model of bootable container images. Once installed, whether -directly via \`bootc install\` (executed as part of a container) or via -another mechanism such as an OS installer tool, further updates can be -pulled via e.g. \`bootc upgrade\`. - -Changes in \`/etc\` and \`/var\` persist. - -# OPTIONS - -**-h**, **\--help** - -: Print help (see a summary with -h) - -# SUBCOMMANDS - -bootc-upgrade(8) - -: Download and queue an updated container image to apply - -bootc-switch(8) - -: Target a new container image reference to boot - -bootc-edit(8) - -: Apply full changes to the host specification - -bootc-status(8) - -: Display status - -bootc-usr-overlay(8) - -: Add a transient writable overlayfs on \`/usr\` that will be - discarded on reboot - -bootc-install(8) - -: Install the running container to a target - -bootc-help(8) - -: Print this message or the help of the given subcommand(s)