Convert inline docs to Puppet Strings

REFERENCE.md

@@ -0,0 +1,273 @@
+# Reference
+
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+### Classes
+
+#### Public Classes
+
+* [`ca_cert`](#ca_cert): This module manages the user defined certificate authority (CA)
+certificates on the server. On OSes that support a distrusted
+folder the module also manages distrusting system default CA certificates.
+
+#### Private Classes
+
+* `ca_cert::params`: OS dependent parameter defaults
+
+### Defined types
+
+* [`ca_cert::ca`](#ca_cert--ca): Manage a user defined CA Certificate on a system.
+On OSes that support distrusting pre-installed CAs this can be managed as well.
+
+## Classes
+
+### <a name="ca_cert"></a>`ca_cert`
+
+This module manages the user defined certificate authority (CA)
+certificates on the server. On OSes that support a distrusted
+folder the module also manages distrusting system default CA certificates.
+
+#### Examples
+
+##### Basic usage
+
+```puppet
+class { 'ca_cert': }
+
+class { 'ca_cert':
+  manage_all_user_CAs => true,
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `ca_cert` class:
+
+* [`package_name`](#-ca_cert--package_name)
+* [`update_cmd`](#-ca_cert--update_cmd)
+* [`trusted_cert_dir`](#-ca_cert--trusted_cert_dir)
+* [`distrusted_cert_dir`](#-ca_cert--distrusted_cert_dir)
+* [`cert_dir_group`](#-ca_cert--cert_dir_group)
+* [`cert_dir_mode`](#-ca_cert--cert_dir_mode)
+* [`ca_file_group`](#-ca_cert--ca_file_group)
+* [`ca_file_mode`](#-ca_cert--ca_file_mode)
+* [`ca_file_extension`](#-ca_cert--ca_file_extension)
+* [`package_ensure`](#-ca_cert--package_ensure)
+* [`always_update_certs`](#-ca_cert--always_update_certs)
+* [`purge_unmanaged_CAs`](#-ca_cert--purge_unmanaged_CAs)
+* [`install_package`](#-ca_cert--install_package)
+* [`ca_certs`](#-ca_cert--ca_certs)
+
+##### <a name="-ca_cert--package_name"></a>`package_name`
+
+Data type: `String[1]`
+
+The name of the package(s) to be installed.
+
+Default value: `$ca_cert::params::package_name`
+
+##### <a name="-ca_cert--update_cmd"></a>`update_cmd`
+
+Data type: `String[1]`
+
+Command to be used to update CA certificates.
+
+Default value: `$ca_cert::params::update_cmd`
+
+##### <a name="-ca_cert--trusted_cert_dir"></a>`trusted_cert_dir`
+
+Data type: `String[1]`
+
+Absolute directory path to the folder containing trusted certificates.
+
+Default value: `$ca_cert::params::trusted_cert_dir`
+
+##### <a name="-ca_cert--distrusted_cert_dir"></a>`distrusted_cert_dir`
+
+Data type: `Optional[String[1]]`
+
+Absolute directory path to the folder containing distrusted certificates.
+
+Default value: `$ca_cert::params::distrusted_cert_dir`
+
+##### <a name="-ca_cert--cert_dir_group"></a>`cert_dir_group`
+
+Data type: `String[1]`
+
+The installed trusted certificate's POSIX group permissions. This uses
+the same syntax as Puppet's native file resource's "group" parameter.
+It defaults to 'system' on AIX, to 'sys' on Solaris, to 'staff' on
+Ubuntu/Debian, and to 'root' in other cases.
+
+Default value: `$ca_cert::params::cert_dir_group`
+
+##### <a name="-ca_cert--cert_dir_mode"></a>`cert_dir_mode`
+
+Data type: `String[1]`
+
+The installed  trusted certificate's POSIX filesystem permissions. This uses
+the same syntax as Puppet's native file resource's "mode" parameter.
+It defaults to '2665' on Debian, and to '0755' on other cases.
+
+Default value: `$ca_cert::params::cert_dir_mode`
+
+##### <a name="-ca_cert--ca_file_group"></a>`ca_file_group`
+
+Data type: `String[1]`
+
+The installed CA certificate's POSIX group permissions. This uses
+the same syntax as Puppet's native file resource's "group" parameter.
+(defaults to 'root' with the exeption of AIX which defaults to 'system')
+
+Default value: `$ca_cert::params::ca_file_group`
+
+##### <a name="-ca_cert--ca_file_mode"></a>`ca_file_mode`
+
+Data type: `String[1]`
+
+The installed CA certificate's POSIX filesystem permissions. This uses
+the same syntax as Puppet's native file resource's "mode" parameter.
+(defaults to '0444', i.e. world-readable)
+
+Default value: `$ca_cert::params::ca_file_mode`
+
+##### <a name="-ca_cert--ca_file_extension"></a>`ca_file_extension`
+
+Data type: `String[1]`
+
+File extenstion for the certificate.
+
+Default value: `$ca_cert::params::ca_file_extension`
+
+##### <a name="-ca_cert--package_ensure"></a>`package_ensure`
+
+Data type: `String[1]`
+
+The ensure parameter to pass to the package resource.
+
+Default value: `'installed'`
+
+##### <a name="-ca_cert--always_update_certs"></a>`always_update_certs`
+
+Data type: `Boolean`
+
+Run the appropriate update CA certificates command for your operating
+system on every Puppet run whether it is needed or not.
+
+Default value: `false`
+
+##### <a name="-ca_cert--purge_unmanaged_CAs"></a>`purge_unmanaged_CAs`
+
+Data type: `Boolean`
+
+When set to true (default: false), user installed CA
+certificates (in the appropriate directories) not managed by this
+module will be purged.
+
+Default value: `false`
+
+##### <a name="-ca_cert--install_package"></a>`install_package`
+
+Data type: `Boolean`
+
+Whether or not this module should install the ca_certificates package.
+The package contains the system default (typically Mozilla) CA
+certificates, as well as the tools required for managing other installed
+CA certificates.
+
+Default value: `true`
+
+##### <a name="-ca_cert--ca_certs"></a>`ca_certs`
+
+Data type: `Hash`
+
+A hash of CA certificates that should be installed as part of the class
+declaration.
+
+Default value: `{}`
+
+## Defined types
+
+### <a name="ca_cert--ca"></a>`ca_cert::ca`
+
+Manage a user defined CA Certificate on a system.
+On OSes that support distrusting pre-installed CAs this can be managed as well.
+
+#### Examples
+
+##### 
+
+```puppet
+ca_cert::ca { 'globalsign_org_intermediate':
+  source => 'http://secure.globalsign.com/cacert/gsorganizationvalsha2g2r1.crt',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `ca_cert::ca` defined type:
+
+* [`ca_text`](#-ca_cert--ca--ca_text)
+* [`source`](#-ca_cert--ca--source)
+* [`ensure`](#-ca_cert--ca--ensure)
+* [`verify_https_cert`](#-ca_cert--ca--verify_https_cert)
+* [`checksum`](#-ca_cert--ca--checksum)
+* [`checksum_type`](#-ca_cert--ca--checksum_type)
+
+##### <a name="-ca_cert--ca--ca_text"></a>`ca_text`
+
+Data type: `Optional[String]`
+
+The text of the CA certificate to install. Required if text is the source
+(default). If a different source is specified this parameter is ignored.
+
+Default value: `undef`
+
+##### <a name="-ca_cert--ca--source"></a>`source`
+
+Data type: `String`
+
+Where the CA certificate should be retrieved from. text, http, https, ftp,
+file, and puppet protocols/sources are supported. If text, then the ca_text parameter
+is also required. Defaults to text.
+
+Default value: `'text'`
+
+##### <a name="-ca_cert--ca--ensure"></a>`ensure`
+
+Data type: `String`
+
+Whether or not the CA certificate should be on a system or not. Valid
+values are trusted, present, distrusted, and absent. Note: untrusted is
+not supported on Debian based systems - using it will log a warning
+and treat it the same as absent. (defaults to trusted)
+
+Default value: `'trusted'`
+
+##### <a name="-ca_cert--ca--verify_https_cert"></a>`verify_https_cert`
+
+Data type: `Boolean`
+
+When retrieving a certificate whether or not to validate the CA of the
+source. (defaults to true)
+
+Default value: `true`
+
+##### <a name="-ca_cert--ca--checksum"></a>`checksum`
+
+Data type: `Optional[String]`
+
+The checksum of the file. (defaults to undef)
+
+Default value: `undef`
+
+##### <a name="-ca_cert--ca--checksum_type"></a>`checksum_type`
+
+Data type: `Optional[String[1]]`
+
+The type of file checksum. (defauts to undef)
+
+Default value: `undef`
+

manifests/ca.pp

@@ -1,40 +1,42 @@
-# ca.pp
+# @summary
+#   Manage a user defined CA Certificate on a system.
+#   On OSes that support distrusting pre-installed CAs this can be managed as well.
 #
-# Manage a CA Certificate on a system. This cannot manage pre-installed
-# operating system CAs.
+# @example
+#   ca_cert::ca { 'globalsign_org_intermediate':
+#     source => 'http://secure.globalsign.com/cacert/gsorganizationvalsha2g2r1.crt',
+#   }
 #
-# === Parameters
-#
-# [*ca_text*]
+# @param ca_text
 #   The text of the CA certificate to install. Required if text is the source
 #   (default). If a different source is specified this parameter is ignored.
-# [*source*]
+#
+# @param source
 #   Where the CA certificate should be retrieved from. text, http, https, ftp,
 #   file, and puppet protocols/sources are supported. If text, then the ca_text parameter
 #   is also required. Defaults to text.
-# [*ensure*]
+#
+# @param ensure
 #   Whether or not the CA certificate should be on a system or not. Valid
 #   values are trusted, present, distrusted, and absent. Note: untrusted is
 #   not supported on Debian based systems - using it will log a warning
 #   and treat it the same as absent. (defaults to trusted)
-# [*verify_https_cert*]
+#
+# @param verify_https_cert
 #   When retrieving a certificate whether or not to validate the CA of the
 #   source. (defaults to true)
-# [*checksum*]
+#
+# @param checksum
 #   The checksum of the file. (defaults to undef)
-# [*checksum_type*]
-#   The type of file checksum. (defauts to undef)
 #
-# === Examples
+# @param checksum_type
+#   The type of file checksum. (defauts to undef)
 #
-# ca_cert::ca { 'globalsign_org_intermediate':
-#   source => 'http://secure.globalsign.com/cacert/gsorganizationvalsha2g2r1.crt',
-# }
 define ca_cert::ca (
-  Optional[String] $ca_text      = undef,
-  String $source                 = 'text',
   String $ensure                 = 'trusted',
+  String $source                 = 'text',
   Boolean $verify_https_cert     = true,
+  Optional[String] $ca_text      = undef,
   Optional[String] $checksum     = undef,
   Optional[String[1]] $checksum_type = undef,
 ) {