aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Nagy <gabriel.nagy@puppet.com>2021-09-30 19:34:09 +0300
committerGabriel Nagy <gabriel.nagy@puppet.com>2021-09-30 19:48:48 +0300
commit5762b07a5447684ab75b4cf0d2ed989d37b25459 (patch)
tree0b276ccba799bf6f097186b7963565cad80d106e
parent8f8c5a5b8f2addd157d353740202539218f2be9c (diff)
downloadpuppet-augeas_core-5762b07a5447684ab75b4cf0d2ed989d37b25459.tar.gz
puppet-augeas_core-5762b07a5447684ab75b4cf0d2ed989d37b25459.tar.bz2
(MODULES-8183) Fix ToC truncation in REFERENCE.md
Puppet Strings prefers a `@summary` tag with a max of 140 characters to fill in the Table of Contents summary. Without this, the description will appear truncated. Add `@summary` and `@example` tags to the type documentation.
-rw-r--r--REFERENCE.md199
-rw-r--r--lib/puppet/type/augeas.rb11
2 files changed, 117 insertions, 93 deletions
diff --git a/REFERENCE.md b/REFERENCE.md
index 5304160..8019100 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -1,42 +1,48 @@
# Reference
+
<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
## Table of Contents
-**Resource types**
+### Resource types
-* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool. Requires: - [Augeas](http://www.augeas.net) - The ruby-augea
+* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool.
## Resource types
-### augeas
-
-Apply a change or an array of changes to the filesystem
-using the augeas tool.
+### <a name="augeas"></a>`augeas`
Requires:
- [Augeas](http://www.augeas.net)
- The ruby-augeas bindings
-Sample usage with a string:
+#### Examples
+
+##### Sample usage with a string:
- augeas{"test1" :
- context => "/files/etc/sysconfig/firstboot",
- changes => "set RUN_FIRSTBOOT YES",
- onlyif => "match other_value size > 0",
- }
+```puppet
-Sample usage with an array and custom lenses:
+augeas { "test1":
+ context => "/files/etc/sysconfig/firstboot",
+ changes => "set RUN_FIRSTBOOT YES",
+ onlyif => "match other_value size > 0",
+}
+```
- augeas{"jboss_conf":
- context => "/files",
- changes => [
- "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
- "set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
- ],
- load_path => "$/usr/share/jbossas/lenses",
- }
+##### Sample usage with an array and custom lenses:
+
+```puppet
+
+augeas { "jboss_conf":
+ context => "/files",
+ changes => [
+ "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
+ "set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
+ ],
+ load_path => "$/usr/share/jbossas/lenses",
+}
+```
#### Properties
@@ -46,27 +52,88 @@ The following properties are available in the `augeas` type.
The expected return code from the augeas command. Should not be set.
-Default value: 0
+Default value: `0`
#### Parameters
The following parameters are available in the `augeas` type.
-##### `name`
+* [`changes`](#changes)
+* [`context`](#context)
+* [`force`](#force)
+* [`incl`](#incl)
+* [`lens`](#lens)
+* [`load_path`](#load_path)
+* [`name`](#name)
+* [`onlyif`](#onlyif)
+* [`provider`](#provider)
+* [`root`](#root)
+* [`show_diff`](#show_diff)
+* [`type_check`](#type_check)
+
+##### <a name="changes"></a>`changes`
-namevar
+The changes which should be applied to the filesystem. This
+can be a command or an array of commands. The following commands are supported:
-The name of this task. Used for uniqueness.
+* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH`
+* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE`
+* `rm <PATH>` --- Removes the node at location `PATH`
+* `remove <PATH>` --- Synonym for `rm`
+* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed
+* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
+* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist
+* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`.
+* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins`
+* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH`
+* `move <PATH> <OTHER PATH>` --- Synonym for `mv`
+* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL`
+* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH`
+* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed
+
+If the `context` parameter is set, that value is prepended to any relative `PATH`s.
-##### `context`
+##### <a name="context"></a>`context`
Optional context path. This value is prepended to the paths of all
changes if the path is relative. If the `incl` parameter is set,
defaults to `/files + incl`; otherwise, defaults to the empty string.
-Default value: ''
+Default value: `''`
+
+##### <a name="force"></a>`force`
+
+Optional command to force the augeas type to execute even if it thinks changes
+will not be made. This does not override the `onlyif` parameter.
+
+Default value: ``false``
+
+##### <a name="incl"></a>`incl`
+
+Load only a specific file, such as `/etc/hosts`. This can greatly speed
+up the execution the resource. When this parameter is set, you must also
+set the `lens` parameter to indicate which lens to use.
+
+##### <a name="lens"></a>`lens`
+
+Use a specific lens, such as `Hosts.lns`. When this parameter is set, you
+must also set the `incl` parameter to indicate which file to load.
+The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html).
+
+##### <a name="load_path"></a>`load_path`
+
+Optional colon-separated list or array of directories; these directories are searched for schema definitions.
+The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync.
+
+Default value: `''`
+
+##### <a name="name"></a>`name`
+
+namevar
+
+The name of this task. Used for uniqueness.
-##### `onlyif`
+##### <a name="onlyif"></a>`onlyif`
Optional augeas command and comparisons to control the execution of this type.
@@ -95,72 +162,22 @@ where:
* `INT` is a number
* `AN_ARRAY` is in the form `['a string', 'another']`
-Default value: ''
+Default value: `''`
-##### `changes`
+##### <a name="provider"></a>`provider`
-The changes which should be applied to the filesystem. This
-can be a command or an array of commands. The following commands are supported:
-
-* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH`
-* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE`
-* `rm <PATH>` --- Removes the node at location `PATH`
-* `remove <PATH>` --- Synonym for `rm`
-* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed
-* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
-* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist
-* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`.
-* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins`
-* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH`
-* `move <PATH> <OTHER PATH>` --- Synonym for `mv`
-* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL`
-* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH`
-* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed
-
-If the `context` parameter is set, that value is prepended to any relative `PATH`s.
+The specific backend to use for this `augeas` resource. You will seldom need to specify this --- Puppet will usually
+discover the appropriate provider for your platform.
-##### `root`
+##### <a name="root"></a>`root`
A file system path; all files loaded by Augeas are loaded underneath `root`.
-Default value: /
-
-##### `load_path`
-
-Optional colon-separated list or array of directories; these directories are searched for schema definitions. The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync.
+Default value: `/`
-Default value: ''
+##### <a name="show_diff"></a>`show_diff`
-##### `force`
-
-Optional command to force the augeas type to execute even if it thinks changes
-will not be made. This does not override the `onlyif` parameter.
-
-Default value: `false`
-
-##### `type_check`
-
-Valid values: `true`, `false`
-
-Whether augeas should perform typechecking. Defaults to false.
-
-Default value: `false`
-
-##### `lens`
-
-Use a specific lens, such as `Hosts.lns`. When this parameter is set, you
-must also set the `incl` parameter to indicate which file to load.
-The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html).
-
-##### `incl`
-
-Load only a specific file, such as `/etc/hosts`. This can greatly speed
-up the execution the resource. When this parameter is set, you must also
-set the `lens` parameter to indicate which lens to use.
-
-##### `show_diff`
-
-Valid values: `true`, `false`, yes, no
+Valid values: ``true``, ``false``, `yes`, `no`
Whether to display differences when the file changes, defaulting to
true. This parameter is useful for files that may contain passwords or
@@ -168,5 +185,13 @@ other secret data, which might otherwise be included in Puppet reports or
other insecure outputs. If the global `show_diff` setting
is false, then no diffs will be shown even if this parameter is true.
-Default value: `true`
+Default value: ``true``
+
+##### <a name="type_check"></a>`type_check`
+
+Valid values: ``true``, ``false``
+
+Whether augeas should perform typechecking. Defaults to false.
+
+Default value: ``false``
diff --git a/lib/puppet/type/augeas.rb b/lib/puppet/type/augeas.rb
index 2303fdc..ef93bce 100644
--- a/lib/puppet/type/augeas.rb
+++ b/lib/puppet/type/augeas.rb
@@ -23,25 +23,24 @@ Puppet::Type.newtype(:augeas) do
feature :execute_changes, 'Actually make the changes'
@doc = <<-'EOT'
- Apply a change or an array of changes to the filesystem
- using the augeas tool.
+ @summary Apply a change or an array of changes to the filesystem using the augeas tool.
Requires:
- [Augeas](http://www.augeas.net)
- The ruby-augeas bindings
- Sample usage with a string:
+ @example Sample usage with a string:
- augeas{"test1" :
+ augeas { "test1":
context => "/files/etc/sysconfig/firstboot",
changes => "set RUN_FIRSTBOOT YES",
onlyif => "match other_value size > 0",
}
- Sample usage with an array and custom lenses:
+ @example Sample usage with an array and custom lenses:
- augeas{"jboss_conf":
+ augeas { "jboss_conf":
context => "/files",
changes => [
"set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",