diff options
author | Tim Smith <tsmith@chef.io> | 2021-06-07 21:53:33 -0700 |
---|---|---|
committer | John McCrae <john.mccrae@progress.com> | 2021-06-14 19:01:11 -0700 |
commit | ed8be6b067d1097f533f4a5c1735fbd87133cc39 (patch) | |
tree | 90d57244be66c90971661a494204d542fddcdaaf | |
parent | 6ef4085bde95e261db8335d4d2ea67a6b156b76d (diff) | |
download | chef-ed8be6b067d1097f533f4a5c1735fbd87133cc39.tar.gz |
Improve the automatically generated docs
Get a few more resources to the point where they are 100% automatically generated. For others there's a long road ahead.
Signed-off-by: Tim Smith <tsmith@chef.io>
-rw-r--r-- | lib/chef/resource/group.rb | 8 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_cask.rb | 3 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_package.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_tap.rb | 3 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_update.rb | 4 | ||||
-rw-r--r-- | lib/chef/resource/openbsd_package.rb | 17 | ||||
-rw-r--r-- | lib/chef/resource/osx_profile.rb | 4 | ||||
-rw-r--r-- | lib/chef/resource/plist.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/reboot.rb | 35 | ||||
-rw-r--r-- | lib/chef/resource/rhsm_repo.rb | 15 | ||||
-rw-r--r-- | lib/chef/resource/ssh_known_hosts_entry.rb | 3 | ||||
-rw-r--r-- | lib/chef/resource/sudo.rb | 4 |
12 files changed, 85 insertions, 15 deletions
diff --git a/lib/chef/resource/group.rb b/lib/chef/resource/group.rb index b76d546b60..545cd0b35d 100644 --- a/lib/chef/resource/group.rb +++ b/lib/chef/resource/group.rb @@ -43,16 +43,16 @@ class Chef property :excluded_members, [String, Array], default: [], coerce: proc { |arg| arg.is_a?(String) ? arg.split(/\s*,\s*/) : arg }, - description: "Remove users from a group. May only be used when append is set to true." + description: "Remove users from a group. May only be used when `append` is set to `true`." property :append, [ TrueClass, FalseClass ], default: false, - description: "How members should be appended and/or removed from a group. When true, members are appended and excluded_members are removed. When false, group members are reset to the value of the members property." + description: "How members should be appended and/or removed from a group. When true, `members` are appended and `excluded_members` are removed. When `false`, group members are reset to the value of the `members` property." property :system, [ TrueClass, FalseClass ], default: false, - description: "Set if a group belongs to a system group. Set to true if the group belongs to a system group." + description: "Set to `true` if the group belongs to a system group." property :non_unique, [ TrueClass, FalseClass ], default: false, - description: "Allow gid duplication. May only be used with the Groupadd provider." + description: "Allow gid duplication. May only be used with the `Groupadd` user resource provider." property :comment, String, introduced: "14.9", diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb index ccfea70708..7a862e8638 100644 --- a/lib/chef/resource/homebrew_cask.rb +++ b/lib/chef/resource/homebrew_cask.rb @@ -51,7 +51,8 @@ class Chef property :owner, [String, Integer], description: "The owner of the Homebrew installation.", - default: lazy { find_homebrew_username } + default: lazy { find_homebrew_username }, + default_description: "Calculated default username"\ action :install, description: "Install an application that is packaged as a Homebrew cask." do if new_resource.install_cask diff --git a/lib/chef/resource/homebrew_package.rb b/lib/chef/resource/homebrew_package.rb index 3874622005..abdc177512 100644 --- a/lib/chef/resource/homebrew_package.rb +++ b/lib/chef/resource/homebrew_package.rb @@ -62,7 +62,7 @@ class Chef DOC property :homebrew_user, [ String, Integer ], - description: "The name or uid of the Homebrew owner to be used by #{ChefUtils::Dist::Infra::PRODUCT} when executing a command." + description: "The name or uid of the Homebrew owner to be used by #{ChefUtils::Dist::Infra::PRODUCT} when executing a command.\n#{ChefUtils::Dist::Infra::PRODUCT}, by default, will attempt to execute a Homebrew command as the owner of the `/usr/local/bin/brew` executable. If that executable does not exist, #{ChefUtils::Dist::Infra::PRODUCT} will attempt to find the user by executing `which brew`. If that executable cannot be found, #{ChefUtils::Dist::Infra::PRODUCT} will print an error message: `Could not find the 'brew' executable in /usr/local/bin or anywhere on the path.`.\nSet this property to specify the Homebrew owner for situations where Chef Infra Client cannot automatically detect the correct owner.'" end end diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb index 9f31463652..05567c5166 100644 --- a/lib/chef/resource/homebrew_tap.rb +++ b/lib/chef/resource/homebrew_tap.rb @@ -51,7 +51,8 @@ class Chef property :owner, String, description: "The owner of the Homebrew installation.", - default: lazy { find_homebrew_username } + default: lazy { find_homebrew_username }, + default_description: "Calculated default username" action :tap, description: "Add a Homebrew tap." do unless tapped?(new_resource.tap_name) diff --git a/lib/chef/resource/homebrew_update.rb b/lib/chef/resource/homebrew_update.rb index 27b352bfb6..ee353f1fe5 100644 --- a/lib/chef/resource/homebrew_update.rb +++ b/lib/chef/resource/homebrew_update.rb @@ -88,7 +88,7 @@ class Chef end end - action :periodic do + action :periodic, description: "Run a periodic update based on the frequency property." do return unless macos? unless brew_up_to_date? @@ -98,7 +98,7 @@ class Chef end end - action :update do + action :update, description: "Run an immediate update." do return unless macos? converge_by "force update new lists of packages" do diff --git a/lib/chef/resource/openbsd_package.rb b/lib/chef/resource/openbsd_package.rb index af632ebb57..eecb188999 100644 --- a/lib/chef/resource/openbsd_package.rb +++ b/lib/chef/resource/openbsd_package.rb @@ -31,6 +31,23 @@ class Chef description "Use the **openbsd_package** resource to manage packages for the OpenBSD platform." introduced "12.1" + examples <<~DOC + **Install a package** + + ```ruby + openbsd_package 'name of package' do + action :install + end + ``` + + **Remove a package** + + ```ruby + openbsd_package 'name of package' do + action :remove + end + ``` + DOC property :package_name, String, description: "An optional property to set the package name if it differs from the resource block's name.", diff --git a/lib/chef/resource/osx_profile.rb b/lib/chef/resource/osx_profile.rb index 3523cb536d..ebeb8e34ca 100644 --- a/lib/chef/resource/osx_profile.rb +++ b/lib/chef/resource/osx_profile.rb @@ -172,7 +172,7 @@ class Chef end end - action :install do + action :install, description: "Install the specified configuration profile." do unless profile_installed? converge_by("install profile #{new_profile_identifier}") do profile_path = write_profile_to_disk @@ -182,7 +182,7 @@ class Chef end end - action :remove do + action :remove, description: "Remove the specified configuration profile." do # Clean up profile after removing it if profile_installed? converge_by("remove profile #{new_profile_identifier}") do diff --git a/lib/chef/resource/plist.rb b/lib/chef/resource/plist.rb index 034b2f319d..4a43605607 100644 --- a/lib/chef/resource/plist.rb +++ b/lib/chef/resource/plist.rb @@ -81,7 +81,7 @@ class Chef group file_group_cmd.stdout.chomp end - action :set do + action :set, description: "Set a value in a plist file." do converge_if_changed :path do converge_by "create new plist: '#{new_resource.path}'" do file new_resource.path do diff --git a/lib/chef/resource/reboot.rb b/lib/chef/resource/reboot.rb index 717b9255b6..be99a397f4 100644 --- a/lib/chef/resource/reboot.rb +++ b/lib/chef/resource/reboot.rb @@ -33,6 +33,41 @@ class Chef " immediate notifications. Delayed notifications produce unintuitive and"\ " probably undesired results." introduced "12.0" + examples <<~DOC + **Reboot a node immediately** + + ```ruby + reboot 'now' do + action :nothing + reason 'Cannot continue Chef run without a reboot.' + delay_mins 2 + end + + execute 'foo' do + command '...' + notifies :reboot_now, 'reboot[now]', :immediately + end + ``` + + **Reboot a node at the end of a Chef Infra Client run** + + ```ruby + reboot 'app_requires_reboot' do + action :request_reboot + reason 'Need to reboot when the run completes successfully.' + delay_mins 5 + end + ``` + + **Cancel a reboot** + + ```ruby + reboot 'cancel_reboot_request' do + action :cancel + reason 'Cancel a previous end-of-run reboot request.' + end + ``` + DOC property :reason, String, description: "A string that describes the reboot action.", diff --git a/lib/chef/resource/rhsm_repo.rb b/lib/chef/resource/rhsm_repo.rb index 502419beb0..03567e004b 100644 --- a/lib/chef/resource/rhsm_repo.rb +++ b/lib/chef/resource/rhsm_repo.rb @@ -26,6 +26,21 @@ class Chef description "Use the **rhsm_repo** resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions." introduced "14.0" + examples <<~DOC + **Enable an RHSM repository** + + ```ruby + rhsm_repo 'rhel-7-server-extras-rpms' + ``` + + **Disable an RHSM repository** + + ```ruby + rhsm_repo 'rhel-7-server-extras-rpms' do + action :disable + end + ``` + DOC property :repo_name, String, description: "An optional property for specifying the repository name if it differs from the resource block's name.", diff --git a/lib/chef/resource/ssh_known_hosts_entry.rb b/lib/chef/resource/ssh_known_hosts_entry.rb index 3040732ce8..a8d45f4c12 100644 --- a/lib/chef/resource/ssh_known_hosts_entry.rb +++ b/lib/chef/resource/ssh_known_hosts_entry.rb @@ -75,7 +75,8 @@ class Chef property :group, [String, Integer], description: "The file group for the ssh_known_hosts file.", - default: lazy { node["root_group"] } + default: lazy { node["root_group"] }, + default_description: "The root user's group depending on platform." property :hash_entries, [TrueClass, FalseClass], description: "Hash the hostname and addresses in the ssh_known_hosts file for privacy.", diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb index 12b01b7f95..d028af80bf 100644 --- a/lib/chef/resource/sudo.rb +++ b/lib/chef/resource/sudo.rb @@ -170,7 +170,7 @@ class Chef end end - action :create, description: "Create a single sudoers config in the sudoers.d directory." do + action :create, description: "Create a single sudoers configuration file in the `sudoers.d` directory." do validate_properties if docker? # don't even put this into resource collection unless we're in docker @@ -228,7 +228,7 @@ class Chef end # Removes a user from the sudoers group - action :delete, description: "Remove a sudoers config from the sudoers.d directory." do + action :delete, description: "Remove a sudoers configuration file from the `sudoers.d` directory." do file "#{new_resource.config_prefix}/sudoers.d/#{new_resource.filename}" do action :delete end |