Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(rust): add tasks using the xtask pattern #1650

Merged
merged 9 commits into from
Oct 4, 2024
Merged

feat(rust): add tasks using the xtask pattern #1650

merged 9 commits into from
Oct 4, 2024

Conversation

imobachgs
Copy link
Contributor

@imobachgs imobachgs commented Sep 30, 2024

While working on Agama's website we wanted to include some documentation about the CLI. Fortunately, clap includes support for generating markdown documentation, man pages, shell completions, etc.

After some research, we found out that the Rust community is adopting the xtask pattern, where you write those tasks using Rust code. And it plays really well with clap, as we can generate those artifcats from the sources.

However, we needed to do some refactoring to expose the CLI as a lib crate so we can use it in our tasks.

This pull request includes the following tasks: manpages, completions and markdown. The first step should be to take advantage of them and generate the artifacts at runtime. It is open for discussion whether we should do the same with the OpenAPI docs.

Generating the man pages
$ cargo xtask manpages                                                                                                                                                              at 15:05:46 
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/xtask manpages`
Generate manpages documentation at out/man

$ ls out/man/                                                                                                                                                                       agama-auth-login.1
agama-auth-logout.1
agama-auth-show.1
agama-auth.1
agama-config-edit.1
agama-config-load.1
agama-config-show.1
agama-config.1
agama-download.1
agama-install.1
agama-logs-list.1
agama-logs-store.1
agama-logs.1
agama-probe.1
agama-profile-autoyast.1
agama-profile-evaluate.1
agama-profile-import.1
agama-profile-validate.1
agama-profile.1
agama-questions-answers.1
agama-questions-ask.1
agama-questions-list.1
agama-questions-mode.1
agama-questions.1
agama.1

Todo

  • Document usage
  • Add a shell-completion package

let mut cmd = Cli::command();
clap_complete::generate_to(aot::Bash, &mut cmd, "agama", &out_dir)?;
clap_complete::generate_to(aot::Fish, &mut cmd, "agama", &out_dir)?;
clap_complete::generate_to(aot::Zsh, &mut cmd, "agama", &out_dir)?;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should probably package each completion package separately with own supplements so on live cd it will install only shell ones.

@imobachgs imobachgs marked this pull request as ready for review October 4, 2024 08:32
@imobachgs imobachgs merged commit d29a167 into master Oct 4, 2024
5 checks passed
@imobachgs imobachgs deleted the xtask branch October 4, 2024 09:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants