Add xtask to generate manpages #792
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
epilys
requested review from
stsquad,
vireshk and
stefano-garzarella
as code owners
epilys
force-pushed
the
xtasks-manpage-gen
branch
2 times, most recently
from
a8c7261 to
9cc75c5
Compare
|
I just realized the man pages don't/won't include an I think we can either do it in this PR or on a followup PR to reduce iterations |
Currently, the main CLI struct type is defined in src/main.rs thus inaccessible when using the crate as a library. Move it to its own module under src/args.rs This will be useful for followup commits that will use src/args.rs directly to generate manual pages using clap_mangen Signed-off-by: Manos Pitsidianakis <[email protected]>
For information about the cargo xtask workflow pattern see: <https://github.com/matklad/cargo-xtask> This commit adds an xtask crate with only one task, "mangen", which generates a ROFF manual page under `target/dist/man` directory for the vhost-device-sound binary. The xtask crate can be configured using cargo features, to help packagers configure what manpages are generated. This generates a manpage in target/dist/man/vhost-device-sound.1 The rendered ROFF output looks like: vhost-device-sound(1) General Commands Manual vhost-device-sound(1) NAME vhost-device-sound - A virtio-sound device using the vhost-user protocol. SYNOPSIS vhost-device-sound <--socket> <--backend> [-h|--help] [-V|--version] DESCRIPTION A virtio-sound device using the vhost-user protocol. OPTIONS --socket=SOCKET vhost-user Unix domain socket path --backend=BACKEND audio backend to be used [possible values: null, pipewire, alsa] -h, --help Print help -V, --version Print version VERSION v0.2.0 REPORTING BUGS Report bugs to the project's issue tracker: https://github.com/rust-vmm/vhost-device vhost-device-sound 0.2.0 vhost-device-sound(1) Fixes rust-vmm#687 ("Add man page for vhost-device-sound") Resolves: rust-vmm#687 Signed-off-by: Manos Pitsidianakis <[email protected]>
Currently, the main CLI struct type is defined in src/main.rs thus inaccessible when using the crate as a library. Move it to its own module under src/args.rs This will be useful in the followup commit that will use src/args.rs directly to generate manual pages using clap_mangen from the xtask crate in this workspace. Signed-off-by: Manos Pitsidianakis <[email protected]>
Add vhost-device-scmi support for the mangen task in xtask binary.
This generates a manpage in target/dist/man/vhost-device-scmi.1
The rendered ROFF output looks like:
vhost-device-scmi(1) General Commands Manual vhost-device-scmi(1)
NAME
vhost-device-scmi - vhost-user SCMI backend device
SYNOPSIS
vhost-device-scmi <-s|--socket-path> [-d|--device] [--help-devices] [-h|--help] [-V|--version]
DESCRIPTION
vhost-user SCMI backend device
OPTIONS
-s, --socket-path=SOCKET_PATH
vhost-user socket to use
-d, --device=DEVICE
Devices to expose
--help-devices
Print help on available devices
-h, --help
Print help
-V, --version
Print version
VERSION
v0.3.0
REPORTING BUGS
Report bugs to the project's issue tracker: https://github.com/rust-vmm/vhost-device
vhost-device-scmi 0.3.0 vhost-device-scmi(1)
Fixes rust-vmm#697 ("Add man page for vhost-device-scmi")
Resolves: rust-vmm#697
Signed-off-by: Manos Pitsidianakis <[email protected]>
Add documentation in a README.md file. Signed-off-by: Manos Pitsidianakis <[email protected]>
Add Packaging and distribution section that mentions the ability to generate manual pages using the xtask crate in this workspace. Signed-off-by: Manos Pitsidianakis <[email protected]>
epilys
force-pushed
the
xtasks-manpage-gen
branch
from
9cc75c5 to
e4f9be7
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
For information about the cargo xtask workflow pattern see: https://github.com/matklad/cargo-xtask
This PR adds an
xtaskcrate with only one task,mangen, which generates a ROFF manual page undertarget/dist/mandirectory for thevhost-device-soundandvhost-device-scmibinaries.The manual pages are placed in
target/dist/man/vhost-device-sound.1andtarget/dist/man/vhost-device-scmi.1.Future support for other crates in this repository is possible and provisioned for.
Fixes #687
Fixes #697
Demo: Rendered man pages as plain text
Generate the manpages:
Plain text rendered with:
man -l /path/to/rust-vmm/vhost-device/target/dist/man/vhost-device-sound.1 | xclipvhost-device-sound(1)man -l /path/to/rust-vmm/vhost-device/target/dist/man/vhost-device-scmi.1 | xclipvhost-device-scmi(1)