Merge pull request #282 from lgarber-akamai/ref/use-class-spec

ref: Move to class-based spec system

docs/modules/domain.md

@@ -48,7 +48,7 @@ Manage Linode Domains.
 | `soa_email` | <center>`str`</center> | <center>Optional</center> | The Start of Authority email address.  **(Updatable)** |
 | `status` | <center>`str`</center> | <center>Optional</center> | Used to control whether this Domain is currently being rendered.  **(Updatable)** |
 | `tags` | <center>`list`</center> | <center>Optional</center> | An array of tags applied to this object.  **(Updatable)** |
-| `ttl_sec` | <center>`int`</center> | <center>Optional</center> | the amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers.  **(Updatable)** |
+| `ttl_sec` | <center>`int`</center> | <center>Optional</center> | The amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers.  **(Updatable)** |
 | `type` | <center>`str`</center> | <center>Optional</center> | Whether this Domain represents the authoritative source of information for the domain it describes (master), or whether it is a read-only copy of a master (slave).  **(Updatable)** |
 
 

docs/modules/firewall.md

@@ -119,7 +119,7 @@ Manage Linode Firewalls.
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
 | `ipv4` | <center>`list`</center> | <center>Optional</center> | A list of IPv4 addresses or networks. Must be in IP/mask format.   |
-| `ipv6` | <center>`list`</center> | <center>Optional</center> | A list of IPv4 addresses or networks. Must be in IP/mask format.   |
+| `ipv6` | <center>`list`</center> | <center>Optional</center> | A list of IPv6 addresses or networks. Must be in IP/mask format.   |
 
 
 

docs/modules/instance.md

@@ -91,9 +91,9 @@ Manage Linode Instances, Configs, and Disks.
 | [`disks` (sub-options)](#disks) | <center>`list`</center> | <center>Optional</center> | A list of Disks to create on the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#disk-create).  **(Updatable)** |
 | [`interfaces` (sub-options)](#interfaces) | <center>`list`</center> | <center>Optional</center> | A list of network interfaces to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#linode-create__request-body-schema).   |
 | `booted` | <center>`bool`</center> | <center>Optional</center> | Whether the new Instance should be booted. This will default to True if the Instance is deployed from an Image or Backup.   |
-| `backup_id` | <center>`int`</center> | <center>Optional</center> | The id of the Backup to restore to the new Instance. May not be provided if “image” is given.   |
-| `wait` | <center>`bool`</center> | <center>Optional</center> | Wait for the instance to have status `running` before returning.  **(Default: `True`)** |
-| `wait_timeout` | <center>`int`</center> | <center>Optional</center> | The amount of time, in seconds, to wait for an instance to have status `running`.  **(Default: `240`)** |
+| `backup_id` | <center>`int`</center> | <center>Optional</center> | The id of the Backup to restore to the new Instance. May not be provided if "image" is given.   |
+| `wait` | <center>`bool`</center> | <center>Optional</center> | Wait for the instance to have status "running" before returning.  **(Default: `True`)** |
+| `wait_timeout` | <center>`int`</center> | <center>Optional</center> | The amount of time, in seconds, to wait for an instance to have status "running".  **(Default: `240`)** |
 
 
 
@@ -107,7 +107,7 @@ Manage Linode Instances, Configs, and Disks.
 | `label` | <center>`str`</center> | <center>**Required**</center> | The label to assign to this config.   |
 | `comments` | <center>`str`</center> | <center>Optional</center> | Arbitrary User comments on this Config.  **(Updatable)** |
 | [`helpers` (sub-options)](#helpers) | <center>`dict`</center> | <center>Optional</center> | Helpers enabled when booting to this Linode Config.   |
-| `kernel` | <center>`str`</center> | <center>Optional</center> | A Kernel ID to boot a Linode with. Defaults to “linode/latest-64bit”.  **(Updatable)** |
+| `kernel` | <center>`str`</center> | <center>Optional</center> | A Kernel ID to boot a Linode with. Defaults to "linode/latest-64bit".  **(Updatable)** |
 | `memory_limit` | <center>`int`</center> | <center>Optional</center> | Defaults to the total RAM of the Linode.  **(Updatable)** |
 | `root_device` | <center>`str`</center> | <center>Optional</center> | The root device to boot.  **(Updatable)** |
 | `run_level` | <center>`str`</center> | <center>Optional</center> | Defines the state of your Linode after booting.  **(Updatable)** |
@@ -122,14 +122,14 @@ Manage Linode Instances, Configs, and Disks.
 
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
-| [`sda` (sub-options)](#sda) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sdb` (sub-options)](#sdb) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sdc` (sub-options)](#sdc) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sdd` (sub-options)](#sdd) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sde` (sub-options)](#sde) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sdf` (sub-options)](#sdf) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sdg` (sub-options)](#sdg) | <center>`dict`</center> | <center>Optional</center> |   |
-| [`sdh` (sub-options)](#sdh) | <center>`dict`</center> | <center>Optional</center> |   |
+| [`sda` (sub-options)](#sda) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sda   |
+| [`sdb` (sub-options)](#sdb) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sdb   |
+| [`sdc` (sub-options)](#sdc) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sdc   |
+| [`sdd` (sub-options)](#sdd) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sdd   |
+| [`sde` (sub-options)](#sde) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sde   |
+| [`sdf` (sub-options)](#sdf) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sdf   |
+| [`sdg` (sub-options)](#sdg) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sdg   |
+| [`sdh` (sub-options)](#sdh) | <center>`dict`</center> | <center>Optional</center> | The device to be mapped to /dev/sdh   |
 
 
 

docs/modules/lke_cluster.md

@@ -159,7 +159,8 @@ Manage Linode LKE clusters.
     - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pools-list__response-samples) for a list of returned fields
 
 
-- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster.NOTE: This value may be unavailable if `skip_polling` is true.
+- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster. 
+NOTE: This value may be unavailable if `skip_polling` is true.
     - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view__responses) for a list of returned fields
 
 

docs/modules/lke_cluster_info.md

@@ -104,7 +104,8 @@ Get info about a Linode LKE cluster.
     - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pools-list__response-samples) for a list of returned fields
 
 
-- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster.NOTE: This value may be unavailable if the cluster is not fully provisioned.
+- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster. 
+NOTE: This value may be unavailable if the cluster is not fully provisioned.
     - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view__responses) for a list of returned fields
 
 

docs/modules/user.md

@@ -57,7 +57,7 @@ Manage a Linode User.
 | `state` | <center>`str`</center> | <center>**Required**</center> | The state of this user.  **(Choices: `present`, `absent`)** |
 | `restricted` | <center>`bool`</center> | <center>Optional</center> | If true, the User must be granted access to perform actions or access entities on this Account.  **(Default: `True`; Updatable)** |
 | `email` | <center>`str`</center> | <center>Optional</center> | The email address for the User. Linode sends emails to this address for account management communications. May be used for other communications as configured.   |
-| [`grants` (sub-options)](#grants) | <center>`dict`</center> | <center>Optional</center> | Update the grants a User has.  **(Updatable)** |
+| [`grants` (sub-options)](#grants) | <center>`dict`</center> | <center>Optional</center> | Update the grants a user has.  **(Updatable)** |
 
 
 
@@ -78,16 +78,16 @@ Manage a Linode User.
 
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
-| `account_access` | <center></center> | <center>Optional</center> | The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users.  **(Choices: `read_only`, `read_write`; Updatable)** |
+| `account_access` | <center>`str`</center> | <center>Optional</center> | The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users.  **(Choices: `read_only`, `read_write`; Updatable)** |
 | `add_databases` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Managed Databases.  **(Default: `False`; Updatable)** |
 | `add_domains` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Domains.  **(Default: `False`; Updatable)** |
-| `add_firewalls` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add firewalls.  **(Default: `False`; Updatable)** |
-| `add_images` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add images.  **(Default: `False`; Updatable)** |
+| `add_firewalls` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Firewalls.  **(Default: `False`; Updatable)** |
+| `add_images` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Images.  **(Default: `False`; Updatable)** |
 | `add_linodes` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Linodes.  **(Default: `False`; Updatable)** |
-| `add_longview` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add LongView.  **(Default: `False`; Updatable)** |
+| `add_longview` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Longview.  **(Default: `False`; Updatable)** |
 | `add_nodebalancers` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add NodeBalancers.  **(Default: `False`; Updatable)** |
 | `add_stackscripts` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add StackScripts.  **(Default: `False`; Updatable)** |
-| `add_volumes` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add volumes.  **(Default: `False`; Updatable)** |
+| `add_volumes` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add Volumes.  **(Default: `False`; Updatable)** |
 | `cancel_account` | <center>`bool`</center> | <center>Optional</center> | If true, this User may add cancel the entire account.  **(Default: `False`; Updatable)** |
 | `longview_subscription` | <center>`bool`</center> | <center>Optional</center> | If true, this User may manage the Account’s Longview subscription.  **(Default: `False`; Updatable)** |
 
@@ -99,7 +99,7 @@ Manage a Linode User.
 
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
-| `type` | <center></center> | <center>**Required**</center> | The type of resource to grant access to.  **(Choices: `domain`, `image`, `linode`, `longview`, `nodebalancer`, `stackscript`, `volume`; Updatable)** |
+| `type` | <center>`str`</center> | <center>**Required**</center> | The type of resource to grant access to.  **(Choices: `domain`, `image`, `linode`, `longview`, `nodebalancer`, `stackscript`, `volume`, `database`; Updatable)** |
 | `id` | <center>`int`</center> | <center>**Required**</center> | The ID of the resource to grant access to.  **(Updatable)** |
 | `permissions` | <center>`str`</center> | <center>**Required**</center> | The level of access this User has to this entity. If null, this User has no access.  **(Choices: `read_only`, `read_write`; Updatable)** |
 

plugins/module_utils/linode_database_shared.py

@@ -4,34 +4,35 @@
 
 from typing import Set, Dict, Any, Callable, Optional
 
+from ansible_specdoc.objects import SpecField, FieldType
 from linode_api4 import ApiError
 
 SPEC_UPDATE_WINDOW = dict(
-    day_of_week=dict(
-        type='int',
+    day_of_week=SpecField(
+        type=FieldType.integer,
         required=True,
-        choices=range(1, 8),
-        description='The day to perform maintenance. 1=Monday, 2=Tuesday, etc.'
+        choices=list(range(1, 8)),
+        description=['The day to perform maintenance. 1=Monday, 2=Tuesday, etc.']
     ),
-    duration=dict(
-        type='int',
+    duration=SpecField(
+        type=FieldType.integer,
         required=True,
         choices=[1, 3],
-        description='The maximum maintenance window time in hours.'
+        description=['The maximum maintenance window time in hours.']
     ),
-    frequency=dict(
-        type='str',
+    frequency=SpecField(
+        type=FieldType.string,
         choices=['weekly', 'monthly'],
         default='weekly',
-        description='Whether maintenance occurs on a weekly or monthly basis.'
+        description=['Whether maintenance occurs on a weekly or monthly basis.']
     ),
-    hour_of_day=dict(
-        type='int',
+    hour_of_day=SpecField(
+        type=FieldType.integer,
         required=True,
-        description='The hour to begin maintenance based in UTC time.',
+        description=['The hour to begin maintenance based in UTC time.'],
     ),
-    week_of_month=dict(
-        type='int',
+    week_of_month=SpecField(
+        type=FieldType.integer,
         description=[
             'The week of the month to perform monthly frequency updates.',
             'Defaults to None.',
@@ -41,6 +42,7 @@
     )
 )
 
+
 def validate_allow_list(allow_list: Set[str]) -> None:
     """Validates the allow_list field params."""
 

plugins/modules/account_info.py

@@ -8,34 +8,32 @@
 # pylint: disable=unused-import
 from typing import List, Any, Optional
 
-from linode_api4 import Volume
+from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField
 
+import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.account_info as docs
 from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase
-from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and
 from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \
     global_requirements
 
-import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.account_info as docs
-
 spec = dict(
     # Disable the default values
-    label=dict(type='str', required=False, doc_hide=True),
-    state=dict(type='str', required=False, doc_hide=True),
+    label=SpecField(type=FieldType.string, required=False, doc_hide=True),
+    state=SpecField(type=FieldType.string, required=False, doc_hide=True),
 )
 
-specdoc_meta = dict(
+SPECDOC_META = SpecDocMeta(
     description=[
         'Get info about a Linode Account.'
     ],
     requirements=global_requirements,
     author=global_authors,
-    spec=spec,
+    options=spec,
     examples=docs.specdoc_examples,
     return_values=dict(
-        account=dict(
+        account=SpecReturnValue(
             description='The account info in JSON serialized form.',
             docs_url='https://www.linode.com/docs/api/account/#account-view__response-samples',
-            type='dict',
+            type=FieldType.dict,
             sample=docs.result_account_samples
         )
     )
@@ -51,7 +49,7 @@ def __init__(self) -> None:
             account=None,
         )
 
-        self.module_arg_spec = spec
+        self.module_arg_spec = SPECDOC_META.ansible_spec
 
         super().__init__(module_arg_spec=self.module_arg_spec,
                          required_one_of=self.required_one_of)