Per UX review of help text, this commit makes several changes over the breadth of the Faces help:
* Preface API-only action summaries/descriptions with "API only." (issue #7775) * Provide both CLI and API info in "returns," with the CLI info first. (issue #7778) * Summaries should be sentences. (Add punctuation.) * First sentences of descriptions should reiterate summaries. (Summaries and descriptions should be displayed far enough apart that this isn't a problem.) * Standardize on "subcommand" instead of "face" when talking about the entity you invoke at the command line. (Use "face" when describing API use.) * Fix outdated or clunky text in several faces. Signed-off-by: nfagerlund <[email protected]> --- Local-branch: ticket/2.7rc/7764-Faces_help_revisions lib/puppet/face/catalog.rb | 52 +++++++++++++++--------- lib/puppet/face/catalog/select.rb | 10 ++-- lib/puppet/face/certificate.rb | 31 ++++++++------ lib/puppet/face/certificate_request.rb | 23 +++++----- lib/puppet/face/certificate_revocation_list.rb | 24 +++++----- lib/puppet/face/config.rb | 10 ++--- lib/puppet/face/facts.rb | 34 +++++++++------ lib/puppet/face/file.rb | 8 ++-- lib/puppet/face/file/download.rb | 10 ++-- lib/puppet/face/help.rb | 12 +++--- lib/puppet/face/help/action.erb | 2 +- lib/puppet/face/help/man.erb | 8 ++-- lib/puppet/face/key.rb | 8 ++-- lib/puppet/face/man.rb | 36 ++++++++--------- lib/puppet/face/node.rb | 25 +++++++----- lib/puppet/face/parser.rb | 9 ++++ lib/puppet/face/plugin.rb | 17 ++++---- lib/puppet/face/report.rb | 16 ++++---- lib/puppet/face/resource.rb | 24 ++++++----- lib/puppet/face/resource_type.rb | 48 +++++++++++++--------- lib/puppet/face/secret_agent.rb | 30 +++++++------- lib/puppet/face/status.rb | 21 +++++---- lib/puppet/indirector/face.rb | 12 +++-- 23 files changed, 261 insertions(+), 209 deletions(-) diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb index 1335154..9bcaa19 100644 --- a/lib/puppet/face/catalog.rb +++ b/lib/puppet/face/catalog.rb @@ -6,25 +6,40 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do summary "Compile, save, view, and convert catalogs." description <<-'EOT' - This face primarily interacts with the compiling subsystem. By default, - it compiles a catalog using the default manifest and the hostname from - `certname`, but you can choose to retrieve a catalog from the server by - specifying '--terminus rest'. You can also choose to print any catalog - in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz) - with '--render-as dot'. + This subcommand deals with catalogs, which are compiled per-node artifacts + generated from a set of Puppet manifests. By default, it interacts with the + compiling subsystem and compiles a catalog using the default manifest and + `certname`, but you can change the source of the catalog with the + `--terminus` option. You can also choose to print any catalog in 'dot' + format (for easy graph viewing with OmniGraffle or Graphviz) with + '--render-as dot'. + EOT + short_description <<-'EOT' + This subcommand deals with catalogs, which are compiled per-node artifacts + generated from a set of Puppet manifests. By default, it interacts with the + compiling subsystem and compiles a catalog using the default manifest and + `certname`; use the `--terminus` option to change the source of the catalog. EOT - get_action(:destroy).summary "Invalid for this face." - get_action(:search).summary "Query format unknown; potentially invalid for this face." + get_action(:destroy).summary "Invalid for this subcommand." + get_action(:search).summary "Invalid for this subcommand." + find = get_action(:find) + find.summary "Retrieve the catalog for a node." + find.arguments "<certname>" + find.returns <<-'EOT' + A serialized catalog. When used from the Ruby API, returns a + Puppet::Resource::Catalog object. + EOT action(:apply) do - summary "Apply a Puppet::Resource::Catalog object." + summary "Find and apply a catalog." description <<-'EOT' Finds and applies a catalog. This action takes no arguments, but - the source of the catalog can be managed with the --terminus option. + the source of the catalog can be managed with the `--terminus` option. EOT returns <<-'EOT' - A Puppet::Transaction::Report object. + Nothing. When used from the Ruby API, returns a Puppet::Transaction::Report + object. EOT examples <<-'EOT' Apply the locally cached catalog: @@ -71,18 +86,17 @@ Puppet::Indirector::Face.define(:catalog, '0.0.1') do action(:download) do summary "Download this node's catalog from the puppet master server." description <<-'EOT' - Retrieves a catalog from the puppet master and saves it to the - local yaml cache. The saved catalog can be used in subsequent - catalog actions by specifying '--terminus rest'. - - This action always contacts the puppet master and will ignore + Retrieves a catalog from the puppet master and saves it to the local yaml + cache. This action always contacts the puppet master and will ignore alternate termini. + + The saved catalog can be used in any subsequent catalog action by specifying + '--terminus yaml' for that action. EOT returns "Nothing." notes <<-'EOT' - As termini are singletons, this action has a side effect of - exporting Puppet::Resource::Catalog.indirection.terminus_class = - yaml to the calling context when used with the Ruby Faces API. The + When used from the Ruby API, this action has a side effect of leaving + Puppet::Resource::Catalog.indirection.terminus_class set to yaml. The terminus must be explicitly re-set for subsequent catalog actions. EOT examples <<-'EOT' diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb index d86963e..de2ca80 100644 --- a/lib/puppet/face/catalog/select.rb +++ b/lib/puppet/face/catalog/select.rb @@ -1,15 +1,15 @@ # Select and show a list of resources of a given type. Puppet::Face.define(:catalog, '0.0.1') do action :select do - summary "Select and show a list of resources of a given type" + summary "Retrieve a catalog and filter it for resources of a given type." arguments "<host> <resource_type>" returns <<-'EOT' - An array of resource objects excised from a catalog. When used at - the command line, returns a list of resource references (Type[title]). + A list of resource references ("Type[title]"). When used from the API, + returns an array of Puppet::Resource objects excised from a catalog. EOT description <<-'EOT' - Retrieves a catalog for the specified host and returns an array of - resources of the given type. + Retrieves a catalog for the specified host, then searches it for all + resources of the requested type. EOT notes <<-'NOTES' By default, this action will retrieve a catalog from Puppet's compiler diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb index cab8817..cb0f61e 100644 --- a/lib/puppet/face/certificate.rb +++ b/lib/puppet/face/certificate.rb @@ -5,9 +5,9 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Provide access to the CA for certificate management" + summary "Provide access to the CA for certificate management." description <<-'EOT' - This face interacts with a local or remote Puppet certificate + This subcommand interacts with a local or remote Puppet certificate authority. Currently, its behavior is not a full superset of `puppet cert`; specifically, it is unable to mimic puppet cert's "clean" option, and its "generate" action submits a CSR rather than creating a @@ -15,10 +15,12 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do EOT option "--ca-location LOCATION" do - summary "The certificate authority to query" + summary "The certificate authority to query (local or remote)." description <<-'EOT' Whether to act on the local certificate authority or one provided by a remote puppet master. Allowed values are 'local' and 'remote.' + + This option is required. EOT before_action do |action, args, options| @@ -27,7 +29,7 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do end action :generate do - summary "Generate a new certificate signing request for HOST." + summary "Generate a new certificate signing request." arguments "<host>" returns "Nothing." description <<-'EOT' @@ -55,8 +57,10 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do action :list do summary "List all certificate signing requests." returns <<-'EOT' - An array of CSR object #inspect strings. This output is currently messy, - but does contain the names of nodes requesting certificates. + An array of #inspect output from CSR objects. This output is + currently messy, but does contain the names of nodes requesting + certificates. This action returns #inspect strings even when used + from the Ruby API. EOT when_invoked do |options| @@ -70,8 +74,7 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do summary "Sign a certificate signing request for HOST." arguments "<host>" returns <<-'EOT' - A string that appears to be an x509 certificate, but is actually - not. Retrieve certificates using the `find` action. + A string that appears to be (but isn't) an x509 certificate. EOT examples <<-'EOT' Sign somenode.puppetlabs.lan's certificate: @@ -88,24 +91,24 @@ Puppet::Indirector::Face.define(:certificate, '0.0.1') do # Indirector action doc overrides find = get_action(:find) - find.summary "Retrieve a certificate" + find.summary "Retrieve a certificate." find.arguments "<host>" find.returns <<-'EOT' An x509 SSL certificate. You will usually want to render this as a - string ('--render-as s'). + string (--render-as s). Note that this action has a side effect of caching a copy of the certificate in Puppet's `ssldir`. EOT destroy = get_action(:destroy) - destroy.summary "Delete a local certificate." + destroy.summary "Delete a certificate." destroy.arguments "<host>" destroy.returns "Nothing." destroy.description <<-'EOT' - Deletes a certificate. This action currently only works with a local CA. + Deletes a certificate. This action currently only works on the local CA. EOT - get_action(:search).summary "Invalid for this face." - get_action(:save).summary "Invalid for this face." + get_action(:search).summary "Invalid for this subcommand." + get_action(:save).summary "Invalid for this subcommand." end diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb index 29cf7dc..12694ba 100644 --- a/lib/puppet/face/certificate_request.rb +++ b/lib/puppet/face/certificate_request.rb @@ -6,20 +6,20 @@ Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do summary "Manage certificate requests." description <<-'EOT' - Retrieves and submits certificate signing requests (CSRs). Invoke - `search` with a dummy key to retrieve all outstanding CSRs, invoke - `find` with a node certificate name to retrieve a specific request, and - invoke `save` to submit a CSR. + This subcommand retrieves and submits certificate signing requests (CSRs). EOT # Per-action doc overrides - get_action(:destroy).summary "Invalid for this face." + get_action(:destroy).summary "Invalid for this subcommand." get_action(:find).summary "Retrieve a single CSR." get_action(:find).arguments "<host>" get_action(:find).returns <<-'EOT' - A single certificate request. In most cases, you will want to render - this as a string ('--render-as s'). + A single certificate request. When used from the Ruby API, returns a + Puppet::SSL::CertificateRequest object. + + RENDERING ISSUES: In most cases, you will want to render this as a string + ('--render-as s'). EOT get_action(:find).examples <<-'EOT' Retrieve a single CSR from the puppet master's CA: @@ -30,16 +30,17 @@ Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do get_action(:search).summary "Retrieve all outstanding CSRs." get_action(:search).arguments "<dummy_key>" get_action(:search).returns <<-'EOT' - An array of certificate request objects. In most cases, you will - want to render this as a string ('--render-as s'). + A list of certificate requests; be sure to to render this as a string + ('--render-as s'). When used from the Ruby API, returns an array of + Puppet::SSL::CertificateRequest objects. EOT get_action(:search).notes "This action always returns all CSRs, but requires a dummy search key." get_action(:search).examples <<-'EOT' - Retrieve all CSRs from the local CA: + Retrieve all CSRs from the local CA (similar to 'puppet cert list'): $ puppet certificate_request search x --terminus ca EOT - get_action(:save).summary "Submit a certificate signing request." + get_action(:save).summary "API only: submit a certificate signing request." get_action(:save).arguments "<x509_CSR>" end diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb index 0525a60..12ba1f7 100644 --- a/lib/puppet/face/certificate_revocation_list.rb +++ b/lib/puppet/face/certificate_revocation_list.rb @@ -6,16 +6,18 @@ Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do summary "Manage the list of revoked certificates." description <<-'EOT' - This face is primarily for retrieving the certificate revocation - list from the CA. Although it exposes search/save/destroy methods, - they shouldn't be used under normal circumstances. + This subcommand is primarily for retrieving the certificate revocation + list from the CA. EOT get_action(:find).summary "Retrieve the certificate revocation list." get_action(:find).arguments "<dummy_key>" get_action(:find).returns <<-'EOT' - A certificate revocation list. You will usually want to render this - as a string ('--render-as s'). + A certificate revocation list. When used from the Ruby API: returns an + OpenSSL::X509::CRL object. + + RENDERING ISSUES: this should usually be rendered as a string + ('--render-as s'). EOT get_action(:find).examples <<-'EXAMPLES' Retrieve a copy of the puppet master's CRL: @@ -27,13 +29,11 @@ Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do get_action(:destroy).arguments "<dummy_key>" get_action(:destroy).returns "Nothing." get_action(:destroy).description <<-'EOT' - Deletes the certificate revocation list. This cannot be done over - REST, but it is possible to both delete the locally cached copy of - the CA's CRL and delete the CA's own copy (if running on the CA - machine and invoked with '--terminus ca'). Needless to say, don't do - this unless you know what you're up to. + Deletes the certificate revocation list. This cannot be done over REST, but + it is possible to delete the locally cached copy or (if run from the CA) the + CA's own copy of the CRL. EOT - get_action(:search).summary "Invalid for this face." - get_action(:save).summary "Invalid for this face." + get_action(:search).summary "Invalid for this subcommand." + get_action(:save).summary "Invalid for this subcommand." end diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb index 6e5bff0..3fce0ed 100644 --- a/lib/puppet/face/config.rb +++ b/lib/puppet/face/config.rb @@ -7,13 +7,11 @@ Puppet::Face.define(:config, '0.0.1') do summary "Interact with Puppet's configuration options." action(:print) do - summary "Examine Puppet's current configuration options." - arguments "(all | <option> [<option> ...]" + summary "Examine Puppet's current configuration settings." + arguments "(all | <setting> [<setting> ...]" returns <<-'EOT' - When called with one option: a single value. - - When called with "all" or multiple options: a list of options and - their values. + A single value when called with one config setting, and a list of settings + and values when called with multiple options or "all." EOT description <<-'EOT' Prints the value of a single configuration option or a list of diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb index 05028a4..99ff14b 100644 --- a/lib/puppet/face/facts.rb +++ b/lib/puppet/face/facts.rb @@ -7,22 +7,28 @@ Puppet::Indirector::Face.define(:facts, '0.0.1') do summary "Retrieve and store facts." description <<-'EOT' - This face manages facts, the collections of normalized system - information used by Puppet. It can read facts directly from the - local system (using the default `facter` terminus), look up facts - reported by other systems, and submit facts to the puppet master. + This subcommand manages facts, which are collections of normalized system + information used by Puppet. It can read facts directly from the local system + (with the default `facter` terminus), look up facts reported by other + systems, and submit facts to the puppet master. - When used with the `rest` terminus, this face is essentially a - front-end to the inventory service REST API. See the inventory - service documentation for more detail. + When used with the `rest` terminus, this subcommand is essentially a front-end + to the inventory service REST API. See the inventory service documentation at + <http://docs.puppetlabs.com/guides/inventory_service.html> for more detail. EOT find = get_action(:find) - find.summary "Retrieve a host's facts." - find.arguments "<host>" - find.returns "A Puppet::Node::Facts object." + find.summary "Retrieve a node's facts." + find.arguments "<node_certname>" + find.returns <<-'EOT' + A hash containing some metadata and (under the "values" key) the set + of facts for the requested node. When used from the Ruby API: A + Puppet::Node::Facts object. + + RENDERING ISSUES: Facts cannot currently be rendered as a string. + EOT find.notes <<-'EOT' - When using the `facter` terminus, the host argument is essentially ignored. + When using the `facter` terminus, the host argument is ignored. EOT find.examples <<-'EOT' Get facts from the local system: @@ -38,13 +44,13 @@ Puppet::Indirector::Face.define(:facts, '0.0.1') do $ puppet facts find somenode.puppetlabs.lan --terminus inventory_active_record --mode master EOT - get_action(:destroy).summary "Invalid for this face." - get_action(:search).summary "Query format unknown; potentially invalid for this face." + get_action(:destroy).summary "Invalid for this subcommand." + get_action(:search).summary "Invalid for this subcommand." action(:upload) do summary "Upload local facts to the puppet master." description <<-'EOT' - Reads facts from the local system using the facter terminus, then + Reads facts from the local system using the `facter` terminus, then saves the returned facts using the rest terminus. EOT returns "Nothing." diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb index 1cf9bc7..f63350e 100644 --- a/lib/puppet/face/file.rb +++ b/lib/puppet/face/file.rb @@ -6,7 +6,7 @@ Puppet::Indirector::Face.define(:file, '0.0.1') do summary "Retrieve and store files in a filebucket" description <<-'EOT' - This face interacts with objects stored in a local or remote + This subcommand interacts with objects stored in a local or remote filebucket. File objects are accessed by their MD5 sum; see the examples for the relevant syntax. EOT @@ -15,7 +15,7 @@ Puppet::Indirector::Face.define(:file, '0.0.1') do --render-as s. Rendering as yaml will return a hash of metadata about the file, including its contents. - This face does not interact with the `clientbucketdir` (the default + This subcommand does not interact with the `clientbucketdir` (the default local filebucket for puppet agent); it interacts with the primary "master"-type filebucket located in the `bucketdir`. If you wish to interact with puppet agent's default filebucket, you'll need to set @@ -40,8 +40,8 @@ Puppet::Indirector::Face.define(:file, '0.0.1') do $ puppet file find md5/9aedba7f413c97dc65895b1cd9421f2c --render-as s EOT - get_action(:search).summary "Invalid for this face." - get_action(:destroy).summary "Invalid for this face." + get_action(:search).summary "Invalid for this subcommand." + get_action(:destroy).summary "Invalid for this subcommand." set_indirection_name :file_bucket_file end diff --git a/lib/puppet/face/file/download.rb b/lib/puppet/face/file/download.rb index 8a300fb..3e67e45 100644 --- a/lib/puppet/face/file/download.rb +++ b/lib/puppet/face/file/download.rb @@ -2,12 +2,12 @@ Puppet::Face.define(:file, '0.0.1') do action :download do |*args| summary "Download a file into the local filebucket." - arguments "( {md5}<checksum> | puppet:///... )" - returns "Nothing" + arguments "( {md5}<checksum> | <puppet_url> )" + returns "Nothing." description <<-EOT - Downloads a file from the puppet master's filebucket and - duplicates it in the local filebucket. This action's checksum - syntax differs from `find`'s, and it can accept a <puppet:///> URL. + Downloads a file from the puppet master's filebucket and duplicates it in + the local filebucket. This action's checksum syntax differs from `find`'s, + and it can accept a <puppet:///> URL. EOT examples <<-'EOT' Download a file by URL: diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb index 9376adf..4a16a0d 100644 --- a/lib/puppet/face/help.rb +++ b/lib/puppet/face/help.rb @@ -10,9 +10,9 @@ Puppet::Face.define(:help, '0.0.1') do summary "Display Puppet help." action(:help) do - summary "Display help about faces and their actions." - arguments "[<face>] [<action>]" - returns "Short help text for the specified face or action." + summary "Display help about Puppet subcommands and their actions." + arguments "[<subcommand>] [<action>]" + returns "Short help text for the specified subcommand or action." examples <<-'EOT' Get help for an action: @@ -20,7 +20,7 @@ Puppet::Face.define(:help, '0.0.1') do EOT option "--version VERSION" do - summary "The version of the face for which to show help." + summary "The version of the subcommand for which to show help." end default @@ -46,7 +46,7 @@ Puppet::Face.define(:help, '0.0.1') do EOT 353.times{i,x=i.divmod(1184);a,b=x.divmod(37);print(c[a]*b)} end - raise ArgumentError, "help only takes two (optional) arguments, a face name, and an action" + raise ArgumentError, "Puppet help only takes two (optional) arguments: a subcommand and an action" end version = :current @@ -55,7 +55,7 @@ Puppet::Face.define(:help, '0.0.1') do version = options[:version] else if args.length == 0 then - raise ArgumentError, "version only makes sense when a face is given" + raise ArgumentError, "Version only makes sense when a Faces subcommand is given" end end end diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb index 94b935f..5242ed2 100644 --- a/lib/puppet/face/help/action.erb +++ b/lib/puppet/face/help/action.erb @@ -2,7 +2,7 @@ USAGE: <%= action.synopsis %> <% end -%> -<%= action.short_description || action.summary || face.summary || "undocumented face" %> +<%= action.short_description || action.summary || face.summary || "undocumented subcommand" %> <% if action.returns -%> RETURNS: <%= action.returns.strip %> diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb index 0122d97..90e2796 100644 --- a/lib/puppet/face/help/man.erb +++ b/lib/puppet/face/help/man.erb @@ -1,4 +1,4 @@ -puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented face." %> +puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented subcommand." %> <%= '=' * (_erbout.length - 1) %> <% if face.synopsis -%> @@ -116,9 +116,9 @@ NOTES <% end # notes if face.respond_to? :indirection -%> -This is an indirector face, which exposes `find`, `search`, `save`, and -`destroy` actions for an indirected subsystem of Puppet. Valid termini -for this face include: +This subcommand is an indirector face, which exposes `find`, `search`, `save`, +and `destroy` actions for an indirected subsystem of Puppet. Valid termini for +this face include: * `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>` diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb index 54c4975..96cfebe 100644 --- a/lib/puppet/face/key.rb +++ b/lib/puppet/face/key.rb @@ -6,10 +6,10 @@ Puppet::Indirector::Face.define(:key, '0.0.1') do summary "Create, save, and remove certificate keys." description <<-'EOT' - Manages certificate private keys. Keys are created for you - automatically when certificate requests are generated with 'puppet - certificate generate', and it should not be necessary to use this action - directly. + This subcommand manages certificate private keys. Keys are created + automatically by puppet agent and when certificate requests are generated + with 'puppet certificate generate'; it should not be necessary to use this + subcommand directly. EOT end diff --git a/lib/puppet/face/man.rb b/lib/puppet/face/man.rb index 38b9202..c43ead3 100644 --- a/lib/puppet/face/man.rb +++ b/lib/puppet/face/man.rb @@ -7,34 +7,32 @@ Puppet::Face.define(:man, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Display Puppet subcommand manual pages." + summary "Display Puppet manual pages." description <<-EOT - The man face, when invoked from the command line, tries very hard to - behave nicely for interactive use. If possible, it delegates to the - ronn(1) command to format the output as a real manual page. - - If ronn(1) is not available, it will use the first of `$MANPAGER`, - `$PAGER`, `less`, `most`, or `more` to paginate the (human-readable) - input text for the manual page. - - We do try hard to ensure that this behaves correctly when used as - part of a pipeline. (Well, we delegate to tools that do the right - thing, which is more or less the same.) + This subcommand displays manual pages for all Puppet subcommands. If the + `ronn` gem (<https://github.com/rtomayko/ronn/>) is installed on your + system, puppet man will display fully-formated man pages. If `ronn` is not + available, puppet man will display the raw (but human-readable) source text + in a pager. EOT notes <<-EOT - We strongly encourage you to install the `ronn` gem on your system, - or otherwise make it available, so that we can display well structured - output from this face. + The pager used for display will be the first found of `$MANPAGER`, `$PAGER`, + `less`, `most`, or `more`. EOT action(:man) do - summary "Display the manual page for a face." - arguments "<face>" - returns "The man data, in markdown format, suitable for consumption by Ronn." + summary "Display the manual page for a Puppet subcommand." + arguments "<subcommand>" + returns <<-'EOT' + The man data, in Markdown format, suitable for consumption by Ronn. + + RENDERING ISSUES: To skip fancy formatting and output the raw Markdown + text (e.g. for use in a pipeline), call this action with '--render-as s'. + EOT examples <<-'EOT' - Get the manual page for a face: + View the manual page for a subcommand: $ puppet man facts EOT diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb index d244127..cd27e0b 100644 --- a/lib/puppet/face/node.rb +++ b/lib/puppet/face/node.rb @@ -5,33 +5,38 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do summary "View and manage node definitions." description <<-'EOT' - This face interacts with node objects, which are used by Puppet to - build a catalog. A node object consists of the node's facts, - environment, node parameters (exposed in the parser as top-scope - variables), and classes. + This subcommand interacts with node objects, which are used by Puppet to + build a catalog. A node object consists of the node's facts, environment, + node parameters (exposed in the parser as top-scope variables), and classes. EOT - get_action(:destroy).summary "Invalid for this face." - get_action(:search).summary "Invalid for this face." - get_action(:save).summary "Invalid for this face." + get_action(:destroy).summary "Invalid for this subcommand." + get_action(:search).summary "Invalid for this subcommand." + get_action(:save).summary "Invalid for this subcommand." find = get_action(:find) find.summary "Retrieve a node object." find.arguments "<host>" find.returns <<-'EOT' - A Puppet::Node object. + A hash containing the node's `classes`, `environment`, `expiration`, `name`, + `parameters` (its facts, combined with any ENC-set parameters), and `time`. + When used from the Ruby API: a Puppet::Node object. RENDERING ISSUES: Rendering as string and json are currently broken; node objects can only be rendered as yaml. EOT find.examples <<-'EOT' - Retrieve an "empty" (no classes, fact and bulit-in parameters only, - and an environment of "production") node: + Retrieve an "empty" (no classes, no ENC-imposed parameters, and an + environment of "production") node: $ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml Retrieve a node using the puppet master's configured ENC: $ puppet node find somenode.puppetlabs.lan --terminus exec --mode master --render-as yaml + + Retrieve the same node from the puppet master: + + $ puppet node find somenode.puppetlabs.lan --terminus rest --render-as yaml EOT end diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb index 8dd3efb..c99cbb7 100644 --- a/lib/puppet/face/parser.rb +++ b/lib/puppet/face/parser.rb @@ -16,6 +16,15 @@ Puppet::Face.define(:parser, '0.0.1') do syncing any resources. If no manifest files are provided, it will validate the default site manifest. EOT + examples <<-'EOT' + Validate the default site manifest at /etc/puppet/manifests/site.pp: + + $ puppet parser validate + + Validate two arbitrary manifest files: + + $ puppet parser validate init.pp vhost.pp + EOT when_invoked do |*args| args.pop files = args diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb index 541468d..76c79f3 100644 --- a/lib/puppet/face/plugin.rb +++ b/lib/puppet/face/plugin.rb @@ -5,13 +5,13 @@ Puppet::Face.define(:plugin, '0.0.1') do summary "Interact with the Puppet plugin system." description <<-'EOT' - This face provides network access to the puppet master's store of + This subcommand provides network access to the puppet master's store of plugins. - EOT - notes <<-'EOT' - The puppet master can serve Ruby code collected from the lib directories + + The puppet master serves Ruby code collected from the `lib` directories of its modules. These plugins can be used on agent nodes to extend - Facter and implement custom types and providers. + Facter and implement custom types and providers. Plugins are normally + downloaded by puppet agent during the course of a run. EOT action :download do @@ -19,12 +19,13 @@ Puppet::Face.define(:plugin, '0.0.1') do description <<-'EOT' Downloads plugins from the configured puppet master. Any plugins downloaded in this way will be used in all subsequent Puppet activity. + This action modifies files on disk. EOT returns <<-'EOT' - A display-formatted list of the files downloaded. If all plugin - files were in sync, this list will be empty. + A list of the files downloaded, or a confirmation that no files were + downloaded. When used from the Ruby API, this action returns an array of + the files downloaded, which will be empty if none were retrieved. EOT - notes "This action modifies files on disk." examples <<-'EOT' Retrieve plugins from the puppet master: diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb index 1345d63..2273710 100644 --- a/lib/puppet/face/report.rb +++ b/lib/puppet/face/report.rb @@ -4,13 +4,13 @@ Puppet::Indirector::Face.define(:report, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Create, display, and submit reports" + summary "Create, display, and submit reports." get_action(:find).summary "Invalid for this face." get_action(:search).summary "Invalid for this face." get_action(:destroy).summary "Invalid for this face." save = get_action(:save) - save.summary "Submit a report." + save.summary "API only: submit a report." save.arguments "<report>" save.returns "Nothing." save.examples <<-'EOT' @@ -27,15 +27,15 @@ Puppet::Indirector::Face.define(:report, '0.0.1') do EOT action(:submit) do - summary "Submit a report object to the puppet master" + summary "API only: submit a report with error handling." description <<-'EOT' - This action is essentially a shortcut and wrapper for the `save` action - with the `rest` terminus, which provides additional details in the - event of a report submission failure. It is not intended for use from - a command line. + API only: Submits a report to the puppet master. This action is + essentially a shortcut and wrapper for the `save` action with the `rest` + terminus, and provides additional details in the event of a failure. EOT + arguments "<report>" examples <<-'EOT' - From secret_agent.rb: + From secret_agent.rb (API example): # ... report = Puppet::Face[:catalog, '0.0.1'].apply diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb index 59f6286..95a2ffc 100644 --- a/lib/puppet/face/resource.rb +++ b/lib/puppet/face/resource.rb @@ -4,19 +4,18 @@ Puppet::Indirector::Face.define(:resource, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "Interact directly with resources via the RAL, like ralsh" + summary "API only: interact directly with resources via the RAL." description <<-'EOT' - This face provides a Ruby API with functionality similar to the puppet - resource (originally ralsh) command line application. It is not intended to be - used from the command line. + API only: this face provides a Ruby API with functionality similar to the + puppet resource (or ralsh) subcommand. EOT - get_action(:destroy).summary "Invalid for this face." + get_action(:destroy).summary "Invalid for this subcommand." search = get_action(:search) - search.summary "Get all resources of a single type." + search.summary "API only: get all resources of a single type." search.arguments "<resource_type>" - search.returns "An array of resource objects." + search.returns "An array of Puppet::Resource objects." search.examples <<-'EOT' Get a list of all user resources (API example): @@ -24,9 +23,9 @@ Puppet::Indirector::Face.define(:resource, '0.0.1') do EOT find = get_action(:find) - find.summary "Get a single resource." + find.summary "API only: get a single resource." find.arguments "<type>/<title>" - find.returns "A resource object." + find.returns "A Puppet::Resource object." find.examples <<-'EOT' Print information about a user on this system (API example): @@ -34,9 +33,12 @@ Puppet::Indirector::Face.define(:resource, '0.0.1') do EOT save = get_action(:save) - save.summary "Create a new resource." + save.summary "API only: create a new resource." + save.description <<-EOT + API only: creates a new resource. + EOT save.arguments "<resource_object>" - save.returns "The same resource object passed." + save.returns "The same resource object passed as an argument." save.examples <<-'EOT' Create a new file resource (API example): diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb index 9d7639f..dc6d9de 100644 --- a/lib/puppet/face/resource_type.rb +++ b/lib/puppet/face/resource_type.rb @@ -4,39 +4,48 @@ Puppet::Indirector::Face.define(:resource_type, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" - summary "View classes, defined resource types, and nodes from all manifests" + summary "View classes, defined resource types, and nodes from all manifests." description <<-'EOT' - This face reads information about the resource collections (classes, + This subcommand reads information about the resource collections (classes, nodes, and defined types) available in Puppet's site manifest and modules. It will eventually be extended to examine native resource types. EOT - - # Action documentation overrides: - get_action(:save).summary = "Invalid for this face." - get_action(:destroy).summary = "Invalid for this face." - - find = get_action(:find) - find.summary "Retrieve info about a resource collection." - find.arguments "<collection_name>" - find.returns <<-'EOT' - A hash of info about one resource collection. This hash will include the - following four keys: + notes <<-'EOT' + The `find` and `search` actions return similar hashes of resource collection + info. These hashes will include the following four keys: * `file` (a string) * `name` (a string) * `type` (<hostclass>, <definition>, or <node>) * `line` (an integer) - It may also include the following keys: + They may optionally include the following keys: * `parent` (<name_of_resource_collection>) * `arguments` (a hash of parameters and default values) * `doc` (a string) + EOT - RENDERING ISSUES: yaml and string output for this indirection are - currently unusable; use json instead. + # Action documentation overrides: + get_action(:save).summary = "Invalid for this subcommand." + get_action(:destroy).summary = "Invalid for this subcommand." + + find = get_action(:find) + find.summary "Retrieve info about a resource collection." + find.arguments "<collection_name>" + find.returns <<-'EOT' + A hash of info about the requested resource collection. When used from the + Ruby API: returns a Puppet::Resource::Type object. + + RENDERING ISSUES: yaml and string output for this indirection are currently + unusable; use json instead. + EOT + find.notes <<-'EOT' + If two resource collections share the same name (e.g. you have both a node + and a class named "default"), `find` will only return one of them. This can + be worked around by using `search` instead. EOT find.examples <<-'EOT' Retrieve info about a specific locally-defined class: @@ -52,10 +61,11 @@ Puppet::Indirector::Face.define(:resource_type, '0.0.1') do search.summary "Search for collections matching a regular expression." search.arguments "<regular_expression>" search.returns <<-'EOT' - An array of resource collection info hashes. (See "RETURNS" under `find`.) + An array of hashes of resource collection info. When used from the Ruby API: + returns an array of Puppet::Resource::Type objects. - RENDERING ISSUES: yaml and string output for this indirection are - currently unusable; use json instead. + RENDERING ISSUES: yaml and string output for this indirection are currently + unusable; use json instead. EOT search.examples <<-'EOT' Retrieve all classes, nodes, and defined types: diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb index 79241da..7771d57 100644 --- a/lib/puppet/face/secret_agent.rb +++ b/lib/puppet/face/secret_agent.rb @@ -6,34 +6,34 @@ Puppet::Face.define(:secret_agent, '0.0.1') do summary "Mimics puppet agent." description <<-'EOT' - This face currently functions as a proof of concept, demonstrating - how Faces allows the separation of application logic from Puppet's - internal systems; compare the actual code for puppet agent. It will - eventually replace puppet agent entirely, and can provide a template - for users who wish to implement agent-like functionality with - non-standard application logic. + This subcommand currently functions as a proof of concept, demonstrating how + the Faces API exposes Puppet's internal systems to application logic; + compare the actual code for puppet agent. It will eventually replace puppet + agent entirely, and can provide a template for users who wish to implement + agent-like functionality with non-standard application logic. EOT action(:synchronize) do default summary "Run secret_agent once." - arguments "[-v | --verbose] [-d | --debug]" # Remove this once options are introspectible description <<-'EOT' - This action mimics a single run of the puppet agent application. - It does not currently daemonize, but can download plugins, submit - facts, retrieve and apply a catalog, and submit a report to the - puppet master. + Mimics a single run of puppet agent. This action does not currently + daemonize, but can download plugins, submit facts, retrieve and apply a + catalog, and submit a report to the puppet master. + EOT + returns <<-'EOT' + Verbose logging from the completed run. When used from the Ruby API: + returns a Puppet::Transaction::Report object. EOT - returns "A Puppet::Transaction::Report object." examples <<-'EOT' Trigger a Puppet run with the configured puppet master: $ puppet secret_agent EOT notes <<-'EOT' - This action requires that the puppet master's `auth.conf` file - allow save access to the `facts` REST terminus. Puppet agent does - not use this facility, and it is turned off by default. See + This action requires that the puppet master's `auth.conf` file allow save + access to the `facts` REST terminus. Puppet agent does not use this + facility, and it is turned off by default. See <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details. EOT diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb index 4ae24e8..690c6b3 100644 --- a/lib/puppet/face/status.rb +++ b/lib/puppet/face/status.rb @@ -6,24 +6,27 @@ Puppet::Indirector::Face.define(:status, '0.0.1') do summary "View puppet server status." - get_action(:destroy).summary "Invalid for this face." - get_action(:save).summary "Invalid for this face." - get_action(:search).summary "Invalid for this face." + get_action(:destroy).summary "Invalid for this subcommand." + get_action(:save).summary "Invalid for this subcommand." + get_action(:search).summary "Invalid for this subcommand." find = get_action(:find) find.summary "Check status of puppet master server." find.arguments "<dummy_key>" - find.returns "A Puppet::Status object, or a low-level connection error." + find.returns <<-'EOT' + A "true" response or a low-level connection error. When used from the Ruby + API: returns a Puppet::Status object. + EOT find.description <<-'EOT' Checks whether a Puppet server is properly receiving and processing - REST requests. This action is only useful when used with '--terminus + HTTP requests. This action is only useful when used with '--terminus rest'; when invoked with the `local` terminus, `find` will always return true. - This action will query the configured puppet master. To query other - servers, including puppet agent nodes started with the --listen - option, you can set set the global --server and --masterport options - on the command line; note that agent nodes listen on port 8139. + Over REST, this action will query the configured puppet master by default. + To query other servers, including puppet agent nodes started with the + <--listen> option, you can set set the global <--server> and <--masterport> + options on the command line; note that agent nodes listen on port 8139. EOT find.notes <<-'EOT' This action requires that the server's `auth.conf` file allow find diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb index bb8ce2c..ead3f4b 100644 --- a/lib/puppet/indirector/face.rb +++ b/lib/puppet/indirector/face.rb @@ -61,11 +61,12 @@ class Puppet::Indirector::Face < Puppet::Face end action :save do - summary "Create or overwrite an object." + summary "API only: create or overwrite an object." arguments "<object>" description <<-EOT - Create or overwrite an object. Save actions cannot currently be - invoked from the command line, and are for API use only. + API only: create or overwrite an object. As the Faces framework does not + currently accept data from STDIN, save actions cannot currently be invoked + from the command line. EOT when_invoked { |key, options| call_indirection_method(:save, key, options) } end @@ -80,8 +81,9 @@ class Puppet::Indirector::Face < Puppet::Face action :info do summary "Print the default terminus class for this face." description <<-EOT - Prints the default terminus class for this face. Note that - different run modes may have different default terminuses. + Prints the default terminus class for this subcommand. Note that different + run modes may have different default termini; when in doubt, specify the + run mode with the '--mode' option. EOT when_invoked do |*args| -- 1.7.3.3 -- You received this message because you are subscribed to the Google Groups "Puppet Developers" 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-dev?hl=en.
