| Puppet Version: 5.5.3
Puppet Server Version: N/A
OS Name/Version: N/A When generating resource type docs content from Puppet codewith Puppet Strings, there are several formatting issues, some unique to certain types and others consistent across all types. These might not be relevant in Platform 6 when many of these types are moved to modules, but they currently require manual reconciliation when compiling reference docs for Platform 5. All Strings output in types
- The puppet doc output lists providers, but the Strings docs do not. For example, this is included in the doc output for the zfs type, but omitted from the Strings output:
code
<h4 id="zfs-attribute-provider">provider</h4> The specific backend to use for this `zfs`
resource. You will seldom need to specify this — Puppet will usually
discover the appropriate provider for your platform. Available providers are:
- [`zfs`](#zfs-provider-zfs)
code
- The puppet doc output lists supported or required features, but the Strings output does not. For example, this appears in the puppet doc output for the service type's enable attribute, but not in the Strings output:
code
Requires features enableable.
code This occurs despite the required feature being listed in the type: code
newproperty(:enable, :required_features => :enableable) do
code and features have their own description strings, which aren't output: code
feature :enableable, "The provider can enable and disable the service",
code
- Defaults in the Strings output are formatted intuitively, as:
code
- Default for: `["osfamily", "solaris"] == `
code
- The puppet doc output instead generates:
code
- Default for `osfamily` == `solaris`.
code
- Neither the doc nor Strings output recognizes when multiple allowed values function identically and should ideally be listed together, such as true and yes or false and no in types using Puppet::Parameter::Boolean.
- The provider support table generated at the end of several types is inconsistent between the puppet doc and Strings output. Specifically, the number of rows per column is inconsistent, and some providers are listed as supported or unsupported differently in each. One especially notable discrepancy is in the mcx type, where the only listed provider (mcxcontent) is listed as supported in the puppet doc output and as unsupported in the Strings output.
Issues with specific types: file Symptom: Many attributes are missing. Apparent cause: Strings does not include attributes defined externally of the main type file. In other words, only the attributes defined in lib/puppet/type/file.rb are output by Strings, and Strings outputs none of the attributes defined in lib/puppet/type/file/*. filebucket Symptom: The port attribute has no description in the Puppet Strings output, despite having a description in the type: code
newparam(:port) do
desc "The port on which the remote server is listening. Defaults to the
value of the `masterport` setting, which is usually %s." % Puppet[:masterport] defaultto { Puppet[:masterport] } code Apparent cause: None, but this might be a unique description that attempts to pass a string value (Puppet[:masterport]) back into the description. yumrepo Symptom: The ABSENT_DOC and YUM_BOOLEAN strings are not rendered, so "Set this to `absent` to remove it from the file completely." appears in the puppet doc output but not in the Strings output, while the regex representing that Boolean expression instead appears in the Strings output as the word "YUM_BOOLEAN". Apparent cause: Puppet Strings does not parse these variables, resulting in missing or incorrect output. zone Symptom: The sysidcfg attribute description's output includes the {{% { ... }%}} brackets in the code.
Apparent cause: desc strings in types are inconsistently wrapped in double quotes, single quotes, heredoc (<<-EOT ... EOT) and different types of brackets (such as {{%q{ ... } }}. zone is the only type using {{% { ... } %}} brackets. zpool Symptom: Quote-escaping backslashes are visible in the Strings output, but not the puppet doc output. For example, the raidz attribute in puppet doc output includes the example: code
raidz => ["disk1 disk2", "disk3 disk4"],
code The same example rendered by Puppet Strings is: code
raidz => [\"disk1 disk2\", \"disk3 disk4\"],
code Apparent cause: Puppet Strings doesn't require quotes to be escaped with backslashes. |
