puppetlabs-toy-chest / prm

Puppet Runtime Manager
Apache License 2.0
3 stars 3 forks source link

Implement `pct help` subsystem #11

Closed sanfrancrisko closed 2 years ago

sanfrancrisko commented 2 years ago

Implement the pct help subsystem. This should provide:

Examples:

prm help --topic validating-bolt-tasks # Pulls up walkthru
prm help validate # Pulls up reference docs for prm validate
prm validate --help # Pulls up reference docs for prm validate
prm help set puppet # Pulls up reference docs for prm set puppet
prm help --topic backend # Concept doc for backends generally
prm help --topic backend-docker # Concept doc for configuring/using docker backend
prm help --tool rubocop # Documentation for the rubocop tool use via PRM, link to upstream tool docs
michaeltlombardi commented 2 years ago

I've done some investigation into custom help and cobra today with some useful findings to summarize here:

  1. Command level help is automatic, so we don't actually need to do any substantial work for surfacing reference docs for commands; prm help set puppet will just work out of the box.
  2. We can write additional subcommands such as prm exec describe puppetlabs/rubocop - with some shared code leveraged to make the same functionality available in validate.
  3. I looked into the cobra concept of additional help commands; unfortunately, I think implementing something (with an example described here) would require metaprogramming to create these on the fly and runs the risk of clobbering the expected behavior as whether prm exec puppetlabs/rubocop --help should return the help as surfaced by the tool or the help about the tool package is not obvious. I suggest instead that we go with the direction in point 2 above for surfacing information about the tool package.
  4. Adding flags to the base help command is possible but poor UX - calling prm help displays the help for the root prm command without any additional flags for help; those flags are visible if the user calls prm help help but this is incredibly non-obvious. So while prm help --topic foo is technically implementable I recommend we instead add an explain subcommand which can read docs by topic etc.

In summary:

michaeltlombardi commented 2 years ago

Resolved by https://github.com/puppetlabs/prm/pull/83