volta-cli/volta

Generate Volta man pages

Open

#1,709 opened on Mar 13, 2024

View on GitHub
 (2 comments) (4 reactions) (0 assignees)Rust (8,309 stars) (189 forks)batch import
enhancementgood first issue

Description

We do not currently supply man pages for Volta. However, it would be relatively straightforward to implement using the clap_mangen crate, since we already use clap for our CLI parser. If someone wants to implement it, it should be a relatively easy first issue.

For a rough idea of how to implement it, you would want to do roughly what we do in src/command/completions.rs:

  • Add clap_mangen as a dependency for that crate.
  • Add a new man_pages module as a sibling to completions and the others.
  • Define a new clap argument with a pub(crate) struct ManPages.
  • Implement Volta’s Command trait for ManPages, including logging events the same basic way Completionts does (so you will also need to add a new ActivityKind etc.) for it.
  • Use the Man struct from clap_mangen to generate the man pages from the command (crate::cli::Volta::command()).
  • Emit the generated roff to the appropriate location. (You will have to see where that is on a per-OS basis!) One note that adds a small bit of complexity here: there is no “default” place to install it on Windows, as far as I know, but we should presumably still support it for someone who wants to read them there.

(Originally posted as a comment by @chriskrycho in https://github.com/volta-cli/volta/issues/1708#issuecomment-1995475302)

Contributor guide

Tech stack
rust
Domain
clidocumentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Rust programmingCLI development
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
Follow the pattern in src/command/completions.rs: add clap mangen dependency, create a new man pages module, define a ManPages struct implementing Volta's Command trait, use Man struct from clap mangen to generate roff from crate::cli::Volta::command(), and emit to OS specific man page directory. See the existing completion implementation for reference.