Issue #14072 has been updated by Jeff Weiss.
In progress in [this branch](https://github.com/jeffweiss/puppet/commits/ticket/master/14072_allow_faces_to_inline_setting_docs). Here's an example from `module` and how it would appear: <code> <pre> Puppet::Face.define(:module, '1.0.0') do extend Puppet::Util::Colors copyright "Puppet Labs", 2012 license "Apache 2 license; see COPYING" summary "Creates, installs and searches for modules on the Puppet Forge." description <<-EOT This subcommand can find, install, and manage modules from the Puppet Forge, a repository of user-contributed Puppet code. It can also generate empty modules, and prepare locally developed modules for release on the Forge. EOT reference_option "environment", "modulepath" </pre> </code> which generates: <code> <pre> $ bin/puppet help module list USAGE: puppet module list [--environment NAME] [--modulepath MODULEPATH] [--tree] [--environment production ] [--modulepath $confdir/modules:/usr/share/puppet/modules ] Lists the installed puppet modules. By default, this action scans the modulepath from puppet.conf's `[main]` block; use the --modulepath option to change which directories are scanned. RETURNS: hash of paths to module objects OPTIONS: --mode MODE - The run mode to use (user, agent, or master). --render-as FORMAT - The rendering format to use. --verbose - Whether to log verbosely. --debug - Whether to log debug information. --environment production - The environment Puppet is running in. For clients (e.g., `puppet agent`) this determines the environment itself, which is used to find modules and much more. For servers (i.e., `puppet master`) this provides the default environment for nodes we know nothing about. --modulepath $confdir/modules:/usr/share/puppet/modules - The search path for modules, as a list of directories separated by the system path separator character. (The POSIX path separator is ':', and the Windows path separator is ';'.) --environment NAME - Which environments' modules to list --modulepath MODULEPATH - Which directories to look for modules in --tree - Whether to show dependencies as a tree view </pre> </code> In that case it's listed twice become it's coming both from the reference_option and the officially declared option, which will be prohibited in #13898. ---------------------------------------- Feature #14072: Allow faces to pull in global settings documentation https://projects.puppetlabs.com/issues/14072#change-60935 Author: Jeff Weiss Status: Accepted Priority: Normal Assignee: Jeff Weiss Category: Target version: Affected Puppet version: Keywords: Branch: As a result of #13898, we can no longer specify an option in a face that collides with the name of a global setting. We do, however, have a need to pull in documentation to the face that says, "Hey, this global setting will really affect the operation of this face and here's it's documentation". For example `--modulepath` for the module face. What would be great would be to allow a face developer to be able to do something like this: <code> <pre> Puppet::Face.define(:module, '1.0.0') do action(:install) do refoption "modulepath" refoption "environment" ... </pre> </code> and the auto-generated documentation will pull in the documentation for `Puppet[:modulepath]` and `Puppet[:environment]` for `module install`. -- You have received this notification because you have either subscribed to it, or are involved in it. To change your notification preferences, please click here: http://projects.puppetlabs.com/my/account -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-bugs?hl=en.
