Skip to content

Commit 5762b07

Browse files
GabrielNagyGabrielNagy
committed
(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.
1 parent 8f8c5a5 commit 5762b07

File tree

2 files changed

+117
-93
lines changed

2 files changed

+117
-93
lines changed

‎REFERENCE.md‎

Lines changed: 112 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,48 @@
11
# Reference
2+
23
<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
34

45
## Table of Contents
56

6-
**Resource types**
7+
### Resource types
78

8-
* [`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
9+
* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool.
910

1011
## Resource types
1112

12-
### augeas
13-
14-
Apply a change or an array of changes to the filesystem
15-
using the augeas tool.
13+
### <a name="augeas"></a>`augeas`
1614

1715
Requires:
1816

1917
- [Augeas](http://www.augeas.net)
2018
- The ruby-augeas bindings
2119

22-
Sample usage with a string:
20+
#### Examples
21+
22+
##### Sample usage with a string:
2323

24-
augeas{"test1" :
25-
context => "/files/etc/sysconfig/firstboot",
26-
changes => "set RUN_FIRSTBOOT YES",
27-
onlyif => "match other_value size > 0",
28-
}
24+
```puppet
2925
30-
Sample usage with an array and custom lenses:
26+
augeas { "test1":
27+
context => "/files/etc/sysconfig/firstboot",
28+
changes => "set RUN_FIRSTBOOT YES",
29+
onlyif => "match other_value size > 0",
30+
}
31+
```
3132

32-
augeas{"jboss_conf":
33-
context => "/files",
34-
changes => [
35-
"set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
36-
"set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
37-
],
38-
load_path => "$/usr/share/jbossas/lenses",
39-
}
33+
##### Sample usage with an array and custom lenses:
34+
35+
```puppet
36+
37+
augeas { "jboss_conf":
38+
context => "/files",
39+
changes => [
40+
"set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",
41+
"set etc/jbossas/jbossas.conf/JAVA_HOME /usr",
42+
],
43+
load_path => "$/usr/share/jbossas/lenses",
44+
}
45+
```
4046

4147
#### Properties
4248

@@ -46,27 +52,88 @@ The following properties are available in the `augeas` type.
4652

4753
The expected return code from the augeas command. Should not be set.
4854

49-
Default value: 0
55+
Default value: `0`
5056

5157
#### Parameters
5258

5359
The following parameters are available in the `augeas` type.
5460

55-
##### `name`
61+
* [`changes`](#changes)
62+
* [`context`](#context)
63+
* [`force`](#force)
64+
* [`incl`](#incl)
65+
* [`lens`](#lens)
66+
* [`load_path`](#load_path)
67+
* [`name`](#name)
68+
* [`onlyif`](#onlyif)
69+
* [`provider`](#provider)
70+
* [`root`](#root)
71+
* [`show_diff`](#show_diff)
72+
* [`type_check`](#type_check)
73+
74+
##### <a name="changes"></a>`changes`
5675

57-
namevar
76+
The changes which should be applied to the filesystem. This
77+
can be a command or an array of commands. The following commands are supported:
5878

59-
The name of this task. Used for uniqueness.
79+
* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH`
80+
* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE`
81+
* `rm <PATH>` --- Removes the node at location `PATH`
82+
* `remove <PATH>` --- Synonym for `rm`
83+
* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed
84+
* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
85+
* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist
86+
* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`.
87+
* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins`
88+
* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH`
89+
* `move <PATH> <OTHER PATH>` --- Synonym for `mv`
90+
* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL`
91+
* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH`
92+
* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed
93+
94+
If the `context` parameter is set, that value is prepended to any relative `PATH`s.
6095

61-
##### `context`
96+
##### <a name="context"></a>`context`
6297

6398
Optional context path. This value is prepended to the paths of all
6499
changes if the path is relative. If the `incl` parameter is set,
65100
defaults to `/files + incl`; otherwise, defaults to the empty string.
66101

67-
Default value: ''
102+
Default value: `''`
103+
104+
##### <a name="force"></a>`force`
105+
106+
Optional command to force the augeas type to execute even if it thinks changes
107+
will not be made. This does not override the `onlyif` parameter.
108+
109+
Default value: ``false``
110+
111+
##### <a name="incl"></a>`incl`
112+
113+
Load only a specific file, such as `/etc/hosts`. This can greatly speed
114+
up the execution the resource. When this parameter is set, you must also
115+
set the `lens` parameter to indicate which lens to use.
116+
117+
##### <a name="lens"></a>`lens`
118+
119+
Use a specific lens, such as `Hosts.lns`. When this parameter is set, you
120+
must also set the `incl` parameter to indicate which file to load.
121+
The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html).
122+
123+
##### <a name="load_path"></a>`load_path`
124+
125+
Optional colon-separated list or array of directories; these directories are searched for schema definitions.
126+
The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync.
127+
128+
Default value: `''`
129+
130+
##### <a name="name"></a>`name`
131+
132+
namevar
133+
134+
The name of this task. Used for uniqueness.
68135

69-
##### `onlyif`
136+
##### <a name="onlyif"></a>`onlyif`
70137

71138
Optional augeas command and comparisons to control the execution of this type.
72139

@@ -95,78 +162,36 @@ where:
95162
* `INT` is a number
96163
* `AN_ARRAY` is in the form `['a string', 'another']`
97164

98-
Default value: ''
165+
Default value: `''`
99166

100-
##### `changes`
167+
##### <a name="provider"></a>`provider`
101168

102-
The changes which should be applied to the filesystem. This
103-
can be a command or an array of commands. The following commands are supported:
104-
105-
* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH`
106-
* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE`
107-
* `rm <PATH>` --- Removes the node at location `PATH`
108-
* `remove <PATH>` --- Synonym for `rm`
109-
* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed
110-
* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL`
111-
* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist
112-
* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`.
113-
* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins`
114-
* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH`
115-
* `move <PATH> <OTHER PATH>` --- Synonym for `mv`
116-
* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL`
117-
* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH`
118-
* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed
119-
120-
If the `context` parameter is set, that value is prepended to any relative `PATH`s.
169+
The specific backend to use for this `augeas` resource. You will seldom need to specify this --- Puppet will usually
170+
discover the appropriate provider for your platform.
121171

122-
##### `root`
172+
##### <a name="root"></a>`root`
123173

124174
A file system path; all files loaded by Augeas are loaded underneath `root`.
125175

126-
Default value: /
127-
128-
##### `load_path`
129-
130-
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.
176+
Default value: `/`
131177

132-
Default value: ''
178+
##### <a name="show_diff"></a>`show_diff`
133179

134-
##### `force`
135-
136-
Optional command to force the augeas type to execute even if it thinks changes
137-
will not be made. This does not override the `onlyif` parameter.
138-
139-
Default value: `false`
140-
141-
##### `type_check`
142-
143-
Valid values: `true`, `false`
144-
145-
Whether augeas should perform typechecking. Defaults to false.
146-
147-
Default value: `false`
148-
149-
##### `lens`
150-
151-
Use a specific lens, such as `Hosts.lns`. When this parameter is set, you
152-
must also set the `incl` parameter to indicate which file to load.
153-
The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html).
154-
155-
##### `incl`
156-
157-
Load only a specific file, such as `/etc/hosts`. This can greatly speed
158-
up the execution the resource. When this parameter is set, you must also
159-
set the `lens` parameter to indicate which lens to use.
160-
161-
##### `show_diff`
162-
163-
Valid values: `true`, `false`, yes, no
180+
Valid values: ``true``, ``false``, `yes`, `no`
164181

165182
Whether to display differences when the file changes, defaulting to
166183
true. This parameter is useful for files that may contain passwords or
167184
other secret data, which might otherwise be included in Puppet reports or
168185
other insecure outputs. If the global `show_diff` setting
169186
is false, then no diffs will be shown even if this parameter is true.
170187

171-
Default value: `true`
188+
Default value: ``true``
189+
190+
##### <a name="type_check"></a>`type_check`
191+
192+
Valid values: ``true``, ``false``
193+
194+
Whether augeas should perform typechecking. Defaults to false.
195+
196+
Default value: ``false``
172197

‎lib/puppet/type/augeas.rb‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,25 +23,24 @@
2323
feature :execute_changes, 'Actually make the changes'
2424

2525
@doc = <<-'EOT'
26-
Apply a change or an array of changes to the filesystem
27-
using the augeas tool.
26+
@summary Apply a change or an array of changes to the filesystem using the augeas tool.
2827
2928
Requires:
3029
3130
- [Augeas](http://www.augeas.net)
3231
- The ruby-augeas bindings
3332
34-
Sample usage with a string:
33+
@example Sample usage with a string:
3534
36-
augeas{"test1" :
35+
augeas { "test1":
3736
context => "/files/etc/sysconfig/firstboot",
3837
changes => "set RUN_FIRSTBOOT YES",
3938
onlyif => "match other_value size > 0",
4039
}
4140
42-
Sample usage with an array and custom lenses:
41+
@example Sample usage with an array and custom lenses:
4342
44-
augeas{"jboss_conf":
43+
augeas { "jboss_conf":
4544
context => "/files",
4645
changes => [
4746
"set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress",

0 commit comments

Comments
 (0)