From 6d992aaf163e96a4cef25d118262c342cde7ed3c Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Mon, 18 Dec 2023 14:53:19 -0500 Subject: [PATCH] docs: Generate docs/man This will help motivate us to improve our man pages, by making them much more visible as pre-generated markdown that can be conveniently viewed from e.g. the Github web UI. For now, anytime we change the CLI we'll need to manually run `cargo xtask man2markdown`, and commit and push the result. This requires `pandoc` in the environment. If this becomes burdensome I will likely investigate doing e.g. a Github action which either automates doing it post-commit, or enforces that it's done as part of the commit which introduces the change. However the problem with the latter will be the `pandoc` requirement. It may make sense to investigate e.g. [clap-markdown](https://docs.rs/clap-markdown/latest/clap_markdown/) in the future instead. Signed-off-by: Colin Walters --- docs/man/README.md | 6 ++ docs/man/bootc-edit.md | 34 +++++++ docs/man/bootc-install-to-disk.md | 111 +++++++++++++++++++++ docs/man/bootc-install-to-filesystem.md | 122 ++++++++++++++++++++++++ docs/man/bootc-install.md | 40 ++++++++ docs/man/bootc-status.md | 38 ++++++++ docs/man/bootc-switch.md | 52 ++++++++++ docs/man/bootc-upgrade.md | 47 +++++++++ docs/man/bootc-usr-overlay.md | 27 ++++++ docs/man/bootc.md | 57 +++++++++++ xtask/src/xtask.rs | 28 +++++- 11 files changed, 561 insertions(+), 1 deletion(-) create mode 100644 docs/man/README.md create mode 100644 docs/man/bootc-edit.md create mode 100644 docs/man/bootc-install-to-disk.md create mode 100644 docs/man/bootc-install-to-filesystem.md create mode 100644 docs/man/bootc-install.md create mode 100644 docs/man/bootc-status.md create mode 100644 docs/man/bootc-switch.md create mode 100644 docs/man/bootc-upgrade.md create mode 100644 docs/man/bootc-usr-overlay.md create mode 100644 docs/man/bootc.md diff --git a/docs/man/README.md b/docs/man/README.md new file mode 100644 index 000000000..17efe1ea1 --- /dev/null +++ b/docs/man/README.md @@ -0,0 +1,6 @@ +# Auto-generated manpages + +These markdown files are automatically generated via +`cargo xtask man2markdown`. + +Start with [bootc.md](bootc.md). diff --git a/docs/man/bootc-edit.md b/docs/man/bootc-edit.md new file mode 100644 index 000000000..3dc067ab6 --- /dev/null +++ b/docs/man/bootc-edit.md @@ -0,0 +1,34 @@ +# NAME + +bootc-edit - Change host specification + +# SYNOPSIS + +**bootc-edit** \[**-f**\|**\--filename**\] \[**\--quiet**\] +\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] + +# DESCRIPTION + +Change host specification + +# OPTIONS + +**-f**, **\--filename**=*FILENAME* + +: Use filename to edit system specification + +**\--quiet** + +: Dont display progress + +**-h**, **\--help** + +: Print help + +**-V**, **\--version** + +: Print version + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-install-to-disk.md b/docs/man/bootc-install-to-disk.md new file mode 100644 index 000000000..21e6080ea --- /dev/null +++ b/docs/man/bootc-install-to-disk.md @@ -0,0 +1,111 @@ +# NAME + +bootc-install-to-disk - Install to the target block device + +# SYNOPSIS + +**bootc-install-to-disk** \[**\--wipe**\] \[**\--block-setup**\] +\[**\--filesystem**\] \[**\--root-size**\] \[**\--target-transport**\] +\[**\--target-imgref**\] \[**\--target-no-signature-verification**\] +\[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] +\[**\--disable-selinux**\] \[**\--karg**\] \[**\--generic-image**\] +\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*DEVICE*\> + +# DESCRIPTION + +Install to the target block device + +# OPTIONS + +**\--wipe** + +: Automatically wipe all existing data on device + +**\--block-setup**=*BLOCK_SETUP* \[default: direct\] + +: Target root block device setup. + +direct: Filesystem written directly to block device tpm2-luks: Bind +unlock of filesystem to presence of the default tpm2 device.\ + +\ +\[*possible values: *direct, tpm2-luks\] + +**\--filesystem**=*FILESYSTEM* + +: Target root filesystem type\ + +\ +\[*possible values: *xfs, ext4, btrfs\] + +**\--root-size**=*ROOT_SIZE* + +: Size of the root partition (default specifier: M). Allowed + specifiers: M (mebibytes), G (gibibytes), T (tebibytes). + +By default, all remaining space on the disk will be used. + +**\--target-transport**=*TARGET_TRANSPORT* \[default: registry\] + +: The transport; e.g. oci, oci-archive. Defaults to \`registry\` + +**\--target-imgref**=*TARGET_IMGREF* + +: Specify the image to fetch for subsequent updates + +**\--target-no-signature-verification** + +: Explicitly opt-out of requiring any form of signature verification + +**\--target-ostree-remote**=*TARGET_OSTREE_REMOTE* + +: Enable verification via an ostree remote + +**\--skip-fetch-check** + +: By default, the accessiblity of the target image will be verified + (just the manifest will be fetched). Specifying this option + suppresses the check; use this when you know the issues it might + find are addressed. + +Two main reasons this might fail: + +\- Forgetting \`\--target-no-signature-verification\` if needed - Using +a registry which requires authentication, but not embedding the pull +secret in the image. + +**\--disable-selinux** + +: Disable SELinux in the target (installed) system. + +This is currently necessary to install \*from\* a system with SELinux +disabled but where the target does have SELinux enabled. + +**\--karg**=*KARG* + +: Add a kernel argument + +**\--generic-image** + +: Perform configuration changes suitable for a \"generic\" disk image. + At the moment: + +\- All bootloader types will be installed - Changes to the system +firmware will be skipped + +**-h**, **\--help** + +: Print help (see a summary with -h) + +**-V**, **\--version** + +: Print version + +\<*DEVICE*\> + +: Target block device for installation. The entire device will be + wiped + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-install-to-filesystem.md b/docs/man/bootc-install-to-filesystem.md new file mode 100644 index 000000000..5382c850e --- /dev/null +++ b/docs/man/bootc-install-to-filesystem.md @@ -0,0 +1,122 @@ +# NAME + +bootc-install-to-filesystem - Install to the target filesystem + +# SYNOPSIS + +**bootc-install-to-filesystem** \[**\--root-mount-spec**\] +\[**\--root-options**\] \[**\--boot-mount-spec**\] \[**\--replace**\] +\[**\--target-transport**\] \[**\--target-imgref**\] +\[**\--target-no-signature-verification**\] +\[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] +\[**\--disable-selinux**\] \[**\--karg**\] \[**\--generic-image**\] +\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*ROOT_PATH*\> + +# DESCRIPTION + +Install to the target filesystem + +# OPTIONS + +**\--root-mount-spec**=*ROOT_MOUNT_SPEC* + +: Source device specification for the root filesystem. For example, + UUID=2e9f4241-229b-4202-8429-62d2302382e1 + +**\--root-options**=*ROOT_OPTIONS* + +: Comma-separated mount options for the root filesystem. For example: + rw,prjquota + +**\--boot-mount-spec**=*BOOT_MOUNT_SPEC* + +: Mount specification for the /boot filesystem. + +At the current time, a separate /boot is required. This restriction will +be lifted in future versions. If not specified, the filesystem UUID will +be used. + +**\--replace**=*REPLACE* + +: Initialize the system in-place; at the moment, only one mode for + this is implemented. In the future, it may also be supported to set + up an explicit \"dual boot\" system\ + +\ +*Possible values:* + +> - wipe: Completely wipe the contents of the target filesystem. This +> cannot be done if the target filesystem is the one the system is +> booted from +> +> - alongside: This is a destructive operation in the sense that the +> bootloader state will have its contents wiped and replaced. +> However, the running system (and all files) will remain in place +> until reboot + +**\--target-transport**=*TARGET_TRANSPORT* \[default: registry\] + +: The transport; e.g. oci, oci-archive. Defaults to \`registry\` + +**\--target-imgref**=*TARGET_IMGREF* + +: Specify the image to fetch for subsequent updates + +**\--target-no-signature-verification** + +: Explicitly opt-out of requiring any form of signature verification + +**\--target-ostree-remote**=*TARGET_OSTREE_REMOTE* + +: Enable verification via an ostree remote + +**\--skip-fetch-check** + +: By default, the accessiblity of the target image will be verified + (just the manifest will be fetched). Specifying this option + suppresses the check; use this when you know the issues it might + find are addressed. + +Two main reasons this might fail: + +\- Forgetting \`\--target-no-signature-verification\` if needed - Using +a registry which requires authentication, but not embedding the pull +secret in the image. + +**\--disable-selinux** + +: Disable SELinux in the target (installed) system. + +This is currently necessary to install \*from\* a system with SELinux +disabled but where the target does have SELinux enabled. + +**\--karg**=*KARG* + +: Add a kernel argument + +**\--generic-image** + +: Perform configuration changes suitable for a \"generic\" disk image. + At the moment: + +\- All bootloader types will be installed - Changes to the system +firmware will be skipped + +**-h**, **\--help** + +: Print help (see a summary with -h) + +**-V**, **\--version** + +: Print version + +\<*ROOT_PATH*\> + +: Path to the mounted root filesystem. + +By default, the filesystem UUID will be discovered and used for +mounting. To override this, use \`\--root-mount-spec\`. + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-install.md b/docs/man/bootc-install.md new file mode 100644 index 000000000..64c4109cf --- /dev/null +++ b/docs/man/bootc-install.md @@ -0,0 +1,40 @@ +# NAME + +bootc-install - Install the running container to a target + +# SYNOPSIS + +**bootc-install** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +\<*subcommands*\> + +# DESCRIPTION + +Install the running container to a target + +# OPTIONS + +**-h**, **\--help** + +: Print help + +**-V**, **\--version** + +: Print version + +# SUBCOMMANDS + +bootc-install-to-disk(8) + +: Install to the target block device + +bootc-install-to-filesystem(8) + +: Install to the target filesystem + +bootc-install-help(8) + +: Print this message or the help of the given subcommand(s) + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-status.md b/docs/man/bootc-status.md new file mode 100644 index 000000000..d4a43ff91 --- /dev/null +++ b/docs/man/bootc-status.md @@ -0,0 +1,38 @@ +# NAME + +bootc-status - Display status + +# SYNOPSIS + +**bootc-status** \[**\--json**\] \[**\--booted**\] +\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] + +# DESCRIPTION + +Display status + +This will output a YAML-formatted object using a schema intended to +match a Kubernetes resource that describes the state of the booted +container. The exact API format is not currently declared stable. + +# OPTIONS + +**\--json** + +: Output in JSON format + +**\--booted** + +: Only display status for the booted deployment + +**-h**, **\--help** + +: Print help (see a summary with -h) + +**-V**, **\--version** + +: Print version + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-switch.md b/docs/man/bootc-switch.md new file mode 100644 index 000000000..5b70cfbf7 --- /dev/null +++ b/docs/man/bootc-switch.md @@ -0,0 +1,52 @@ +# NAME + +bootc-switch - Target a new container image reference to boot + +# SYNOPSIS + +**bootc-switch** \[**\--quiet**\] \[**\--transport**\] +\[**\--no-signature-verification**\] \[**\--ostree-remote**\] +\[**\--retain**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] +\<*TARGET*\> + +# DESCRIPTION + +Target a new container image reference to boot + +# OPTIONS + +**\--quiet** + +: Dont display progress + +**\--transport**=*TRANSPORT* \[default: registry\] + +: The transport; e.g. oci, oci-archive. Defaults to \`registry\` + +**\--no-signature-verification** + +: Explicitly opt-out of requiring any form of signature verification + +**\--ostree-remote**=*OSTREE_REMOTE* + +: Enable verification via an ostree remote + +**\--retain** + +: Retain reference to currently booted image + +**-h**, **\--help** + +: Print help + +**-V**, **\--version** + +: Print version + +\<*TARGET*\> + +: Target image to use for the next boot + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-upgrade.md b/docs/man/bootc-upgrade.md new file mode 100644 index 000000000..3fea5e767 --- /dev/null +++ b/docs/man/bootc-upgrade.md @@ -0,0 +1,47 @@ +# NAME + +bootc-upgrade - Look for updates to the booted container image + +# SYNOPSIS + +**bootc-upgrade** \[**\--quiet**\] \[**\--touch-if-changed**\] +\[**\--check**\] \[**\--apply**\] \[**-h**\|**\--help**\] +\[**-V**\|**\--version**\] + +# DESCRIPTION + +Look for updates to the booted container image + +# OPTIONS + +**\--quiet** + +: Dont display progress + +**\--touch-if-changed**=*TOUCH_IF_CHANGED* + +: + +**\--check** + +: Check if an update is available without applying it + +**\--apply** + +: Restart or reboot into the new target image. + +Currently, this option always reboots. In the future this command will +detect the case where no kernel changes are queued, and perform a +userspace-only restart. + +**-h**, **\--help** + +: Print help (see a summary with -h) + +**-V**, **\--version** + +: Print version + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc-usr-overlay.md b/docs/man/bootc-usr-overlay.md new file mode 100644 index 000000000..e63ccf047 --- /dev/null +++ b/docs/man/bootc-usr-overlay.md @@ -0,0 +1,27 @@ +# NAME + +bootc-usr-overlay - Add a transient writable overlayfs on \`/usr\` that +will be discarded on reboot + +# SYNOPSIS + +**bootc-usr-overlay** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] + +# DESCRIPTION + +Add a transient writable overlayfs on \`/usr\` that will be discarded on +reboot + +# OPTIONS + +**-h**, **\--help** + +: Print help + +**-V**, **\--version** + +: Print version + +# VERSION + +v0.1.0 diff --git a/docs/man/bootc.md b/docs/man/bootc.md new file mode 100644 index 000000000..c4e91815e --- /dev/null +++ b/docs/man/bootc.md @@ -0,0 +1,57 @@ +# 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) + +: Look for updates to the booted container image + +bootc-switch(8) + +: Target a new container image reference to boot + +bootc-edit(8) + +: Change 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) diff --git a/xtask/src/xtask.rs b/xtask/src/xtask.rs index 09b5f73d9..9e120231a 100644 --- a/xtask/src/xtask.rs +++ b/xtask/src/xtask.rs @@ -2,7 +2,7 @@ use std::fs::File; use std::io::{BufRead, BufReader, BufWriter, Cursor, Write}; use std::process::{Command, Stdio}; -use anyhow::{Context, Result}; +use anyhow::{anyhow, Context, Result}; use camino::{Utf8Path, Utf8PathBuf}; use fn_error_context::context; use xshell::{cmd, Shell}; @@ -21,6 +21,7 @@ fn main() { const TASKS: &[(&str, fn(&Shell) -> Result<()>)] = &[ ("vendor", vendor), ("manpages", manpages), + ("man2markdown", man2markdown), ("package", package), ("package-srpm", package_srpm), ("custom-lints", custom_lints), @@ -87,6 +88,31 @@ fn manpages(sh: &Shell) -> Result<()> { Ok(()) } +/// Generate markdown files (converted from the man pages, which are generated +/// from the Rust sources) into docs/man. This process is currently manual. +#[context("man2markdown")] +fn man2markdown(sh: &Shell) -> Result<()> { + manpages(sh)?; + for ent in std::fs::read_dir("target/man")? { + let ent = ent?; + let path = &ent.path(); + if path.extension().and_then(|s| s.to_str()) != Some("8") { + continue; + } + let filename = path + .file_stem() + .and_then(|name| name.to_str()) + .ok_or_else(|| anyhow!("Expected filename in {path:?}"))?; + let target = format!("docs/man/{filename}.md"); + cmd!( + sh, + "pandoc --from=man --to=markdown --output={target} {path}" + ) + .run()?; + } + Ok(()) +} + /// Return a string formatted version of the git commit timestamp, up to the minute /// but not second because, well, we're not going to build more than once a second. #[context("Finding git timestamp")]