diff options
author | Tim Smith <tsmith84@gmail.com> | 2020-05-28 11:11:23 -0700 |
---|---|---|
committer | Tim Smith <tsmith84@gmail.com> | 2020-05-28 11:11:23 -0700 |
commit | 008f083d470cf747ae4b56dea77bf75ad8599263 (patch) | |
tree | 53f61e246c33a86cf14d6e284eb3a29ab8d8a8d2 | |
parent | b49c1d7f1eeed3ceb7bc35406dd802f582a3c25c (diff) | |
download | chef-008f083d470cf747ae4b56dea77bf75ad8599263.tar.gz |
Improve auto-generated docs
Add more descriptions and examples
Remove some smart quotes
Make sure homebrew_package gets tagged as supporting multi-package
Signed-off-by: Tim Smith <tsmith@chef.io>
-rw-r--r-- | RELEASE_NOTES.md | 2 | ||||
-rw-r--r-- | docs/dev/design_documents/resource_load_and_converge_methods.md | 1 | ||||
-rw-r--r-- | docs/dev/how_to/bumping_the_major_version.md | 6 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_package.rb | 31 | ||||
-rw-r--r-- | lib/chef/resource/kernel_module.rb | 15 | ||||
-rw-r--r-- | lib/chef/resource/plist.rb | 16 | ||||
-rw-r--r-- | lib/chef/resource/template.rb | 2 | ||||
-rwxr-xr-x | tasks/docs.rb | 2 |
8 files changed, 63 insertions, 12 deletions
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 8612ac45f3..29cfb55036 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1372,6 +1372,7 @@ Chef Infra Client's Data Collection subsystem is used to report node changes dur A new `copy_properties_from` method for custom resources allows you copy properties from your custom resource into other resources you are calling, so you can avoid unnecessarily repeating code. To inherit all the properties of another resource: + ```ruby resource_name :my_resource @@ -1386,6 +1387,7 @@ end ``` To selectively inherit certain properties from a resource: + ```ruby resource_name :my_resource diff --git a/docs/dev/design_documents/resource_load_and_converge_methods.md b/docs/dev/design_documents/resource_load_and_converge_methods.md index b7046d1892..00b074578b 100644 --- a/docs/dev/design_documents/resource_load_and_converge_methods.md +++ b/docs/dev/design_documents/resource_load_and_converge_methods.md @@ -30,7 +30,6 @@ When the resource writer defines `load_current_value` on the resource class, it 2. Copy all non-desired-state values from the desired resource into the new instance. 3. Call `load_current_value` on the new instance. - ```ruby class File < Chef::Resource property :path, name_attribute: true diff --git a/docs/dev/how_to/bumping_the_major_version.md b/docs/dev/how_to/bumping_the_major_version.md index 17332bf765..ff93f5bcf6 100644 --- a/docs/dev/how_to/bumping_the_major_version.md +++ b/docs/dev/how_to/bumping_the_major_version.md @@ -8,7 +8,7 @@ Chef consumes Ohai from GitHub as both a runtime dependency and a testing depend ### Create a new stable branch of Ohai -On your local machine fork the current master branch to a new stable branch. For example: `git checkout -b 15-stable`. You’ll then want to edit the Expeditor config.yml file to update the branch configs like this: +On your local machine fork the current master branch to a new stable branch. For example: `git checkout -b 15-stable`. You'll then want to edit the Expeditor config.yml file to update the branch configs like this: https://github.com/chef/ohai/commit/ad208165619425dd7886b2de3f168b49ded25146 @@ -29,9 +29,9 @@ On your local machine fork the current master branch to a new stable branch. For ### Create a branch to fixup your new stable branch for release -Once you’ve forked to a new stable branch such as `chef-15` you’ll want to create a new branch so you can build a PR, which will get this branch ready for release: +Once you've forked to a new stable branch such as `chef-15` you'll want to create a new branch so you can build a PR, which will get this branch ready for release: -- In ./expeditor/config.yml add the version_constraint for the new branch, update the version_constraint for master to match the new major version, and remove all the update_dep.sh subscriptions which don’t work against stable branches. +- In ./expeditor/config.yml add the version_constraint for the new branch, update the version_constraint for master to match the new major version, and remove all the update_dep.sh subscriptions which don't work against stable branches. - In readme.md update the buildkite badge to point to the new stable branch image and link instead of pointing to master. - In kitchen-tests/Gemfile update the Ohai branch to point to the new Ohai stable - In kitchen-tests/kitchen.yml update chef_version to be your new stable version and not current. Ex: 15 diff --git a/lib/chef/resource/homebrew_package.rb b/lib/chef/resource/homebrew_package.rb index 71a9ffde38..c3b34395f6 100644 --- a/lib/chef/resource/homebrew_package.rb +++ b/lib/chef/resource/homebrew_package.rb @@ -29,8 +29,37 @@ class Chef provides :homebrew_package provides :package, os: "darwin" - description "Use the **homebrew_package** resource to manage packages for the macOS platform." + description "Use the **homebrew_package** resource to manage packages for the macOS platform. Note: Starting with #{Chef::Dist::PRODUCT} 16 the homebrew resource now accepts an array of packages for isntalling multiple packages at once." introduced "12.0" + examples <<~DOC + **Install a package**: + + ```ruby + homebrew_package 'git' + ``` + + **Install multiple packages at once**: + + ```ruby + homebrew_package %w(git fish ruby) + ``` + + **Specify the Homebrew user with a UUID** + + ```ruby + homebrew_package 'git' do + homebrew_user 1001 + end + ``` + + **Specify the Homebrew user with a string**: + + ```ruby + homebrew_package 'vim' do + homebrew_user 'user1' + end + ``` + DOC property :homebrew_user, [ String, Integer ], description: "The name or uid of the Homebrew owner to be used by #{Chef::Dist::PRODUCT} when executing a command." diff --git a/lib/chef/resource/kernel_module.rb b/lib/chef/resource/kernel_module.rb index c3b3dba9d5..87a1d79d24 100644 --- a/lib/chef/resource/kernel_module.rb +++ b/lib/chef/resource/kernel_module.rb @@ -19,11 +19,14 @@ class Chef introduced "14.3" examples <<~DOC Install and load a kernel module, and ensure it loads on reboot. + ```ruby kernel_module 'loop' ``` + Install and load a kernel with a specific set of options, and ensure it loads on reboot. Consult kernel module documentation for specific options that are supported. + ```ruby kernel_module 'loop' do options [ @@ -32,31 +35,41 @@ class Chef ] end ``` + Load a kernel module. + ```ruby kernel_module 'loop' do action :load end ``` - Unload a kernel module and remove module config, so it doesn’t load on reboot. + + Unload a kernel module and remove module config, so it doesn't load on reboot. + ```ruby kernel_module 'loop' do action :uninstall end ``` + Unload kernel module. + ```ruby kernel_module 'loop' do action :unload end ``` + Blacklist a module from loading. + ```ruby kernel_module 'loop' do action :blacklist end ``` + Disable a kernel module. + ```ruby kernel_module 'loop' do action :disable diff --git a/lib/chef/resource/plist.rb b/lib/chef/resource/plist.rb index 944eea18e9..e880ce70a4 100644 --- a/lib/chef/resource/plist.rb +++ b/lib/chef/resource/plist.rb @@ -29,13 +29,21 @@ class Chef description "Use the **plist** resource to set config values in plist files on macOS systems." introduced "16.0" - property :path, String, name_property: true + property :path, String, name_property: true, + description: "The path on disk to the plist file." + property :entry, String property :value, [TrueClass, FalseClass, String, Integer, Float, Hash] property :encoding, String, default: "binary" - property :owner, String, default: "root" - property :group, String, default: "wheel" - property :mode, [String, Integer] + + property :owner, String, default: "root", + description: "The owner of the plist file." + + property :group, String, default: "wheel", + description: "The group of the plist file." + + property :mode, [String, Integer], + description: "The file mode of the plist file. Ex: '644'" PLISTBUDDY_EXECUTABLE = "/usr/libexec/PlistBuddy".freeze DEFAULTS_EXECUTABLE = "/usr/bin/defaults".freeze diff --git a/lib/chef/resource/template.rb b/lib/chef/resource/template.rb index 1ac99b3d13..0ffa2194d8 100644 --- a/lib/chef/resource/template.rb +++ b/lib/chef/resource/template.rb @@ -69,7 +69,7 @@ class Chef property :local, [ TrueClass, FalseClass ], default: false, desired_state: false, - description: "Load a template from a local path. By default, the #{Chef::Dist::CLIENT} loads templates from a cookbook’s /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node." + description: "Load a template from a local path. By default, the #{Chef::Dist::CLIENT} loads templates from a cookbook's /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node." # Declares a helper method to be defined in the template context when # rendering. diff --git a/tasks/docs.rb b/tasks/docs.rb index ef77cd03a9..c53b4aa58e 100755 --- a/tasks/docs.rb +++ b/tasks/docs.rb @@ -184,7 +184,7 @@ namespace :docs_site do properties = {} # these package properties support passing arrays for the package name - properties["common_resource_functionality_multiple_packages"] = true if %w{yum_package apt_package zypper_package homebrew_package dnf_package pacman_package}.include?(name) + properties["common_resource_functionality_multiple_packages"] = true if %w{yum_package apt_package zypper_package homebrew_package dnf_package pacman_package homebrew_package}.include?(name) properties["common_resource_functionality_resources_common_windows_security"] = true if name == "remote_directory" |