doc: Add disclaimer to documentation for modules that consume beta en…

…dpoints (#476)

* Add beta endpoint disclaimer

* oops

* oops

* fix lint

* fix examples

docs/modules/account_availability_info.md

@@ -2,6 +2,8 @@
 
 Get info about a Linode Account Availability.
 
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
 - [Examples](#examples)
 - [Parameters](#parameters)
 - [Return Values](#return-values)
@@ -11,6 +13,7 @@ Get info about a Linode Account Availability.
 ```yaml
 - name: Get info about the current Linode account availability
   linode.cloud.account_info: 
+    api_version: v4beta
     region: us-east
 
 ```

docs/modules/account_availability_list.md

@@ -2,6 +2,8 @@
 
 List and filter on Account Availabilitys.
 
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
 - [Examples](#examples)
 - [Parameters](#parameters)
 - [Return Values](#return-values)
@@ -10,7 +12,8 @@ List and filter on Account Availabilitys.
 
 ```yaml
 - name: List all of the region resource availabilities to the account
-  linode.cloud.account_availability_list: {}
+  linode.cloud.account_availability_list:
+    api_version: v4beta
 ```
 
 

docs/modules/ip_share.md

@@ -2,6 +2,8 @@
 
 Manage the Linode shared IPs.
 
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
 - [Examples](#examples)
 - [Parameters](#parameters)
 - [Return Values](#return-values)
@@ -11,6 +13,7 @@ Manage the Linode shared IPs.
 ```yaml
 - name: Configure the Linode shared IPs.
   linode.cloud.ip_share:
+    api_version: v4beta
     linode_id: 12345
     ips: ["192.0.2.1", "2001:db8:3c4d:15::"]
 ```

docs/modules/vlan_info.md

@@ -2,6 +2,8 @@
 
 Get info about a Linode VLAN.
 
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
 - [Examples](#examples)
 - [Parameters](#parameters)
 - [Return Values](#return-values)
@@ -11,6 +13,7 @@ Get info about a Linode VLAN.
 ```yaml
 - name: Get info about a VLAN by label
   linode.cloud.vlan_info:
+    api_version: v4beta
     label: example-vlan
 ```
 

docs/modules/vlan_list.md

@@ -2,6 +2,8 @@
 
 List and filter on Linode VLANs.
 
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
 - [Examples](#examples)
 - [Parameters](#parameters)
 - [Return Values](#return-values)
@@ -10,12 +12,14 @@ List and filter on Linode VLANs.
 
 ```yaml
 - name: List all of the VLANs for the current Linode Account
-  linode.cloud.vlan_list: {}
+  linode.cloud.vlan_list:
+    api_version: v4beta
 ```
 
 ```yaml
 - name: List all VLANs in the us-southeast region
   linode.cloud.vlan_list:
+    api_version: v4beta
     filters:
       - name: region
         values: us-southeast

plugins/module_utils/doc_fragments/account_availability_info.py

@@ -11,5 +11,6 @@
 specdoc_examples = ['''
 - name: Get info about the current Linode account availability
   linode.cloud.account_info: 
+    api_version: v4beta
     region: us-east
 ''']

plugins/module_utils/doc_fragments/account_availability_list.py

@@ -2,7 +2,8 @@
 
 specdoc_examples = ['''
 - name: List all of the region resource availabilities to the account
-  linode.cloud.account_availability_list: {}''']
+  linode.cloud.account_availability_list:
+    api_version: v4beta''']
 
 result_account_availabilities_samples = ['''[
     {

plugins/module_utils/doc_fragments/ip_share.py

@@ -2,6 +2,7 @@
 specdoc_examples = ['''
 - name: Configure the Linode shared IPs.
   linode.cloud.ip_share:
+    api_version: v4beta
     linode_id: 12345
     ips: ["192.0.2.1", "2001:db8:3c4d:15::"]''']
 

plugins/module_utils/doc_fragments/vlan_info.py

@@ -3,6 +3,7 @@
 specdoc_examples = ['''
 - name: Get info about a VLAN by label
   linode.cloud.vlan_info:
+    api_version: v4beta
     label: example-vlan''']
 
 result_vlan_samples = ['''{

plugins/module_utils/doc_fragments/vlan_list.py

@@ -2,9 +2,11 @@
 
 specdoc_examples = ['''
 - name: List all of the VLANs for the current Linode Account
-  linode.cloud.vlan_list: {}''', '''
+  linode.cloud.vlan_list:
+    api_version: v4beta''', '''
 - name: List all VLANs in the us-southeast region
   linode.cloud.vlan_list:
+    api_version: v4beta
     filters:
       - name: region
         values: us-southeast

plugins/module_utils/linode_common_info.py

@@ -12,6 +12,7 @@
     LinodeModuleBase,
 )
 from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
+    BETA_DISCLAIMER,
     global_authors,
     global_requirements,
 )
@@ -95,12 +96,14 @@ def __init__(
         params: List[InfoModuleParam] = None,
         attributes: List[InfoModuleAttr] = None,
         examples: List[str] = None,
+        requires_beta: bool = False,
     ) -> None:
         self.primary_result = primary_result
         self.secondary_results = secondary_results or []
         self.params = params or []
         self.attributes = attributes or []
         self.examples = examples or []
+        self.requires_beta = requires_beta
 
         self.module_arg_spec = self.spec.ansible_spec
         self.results: Dict[str, Any] = {
@@ -195,10 +198,15 @@ def spec(self):
             for v in [self.primary_result] + self.secondary_results
         }
 
+        description = [
+            f"Get info about a Linode {self.primary_result.display_name}."
+        ]
+
+        if self.requires_beta:
+            description.append(BETA_DISCLAIMER)
+
         return SpecDocMeta(
-            description=[
-                f"Get info about a Linode {self.primary_result.display_name}."
-            ],
+            description=description,
             requirements=global_requirements,
             author=global_authors,
             options=options,

plugins/module_utils/linode_common_list.py

@@ -12,6 +12,7 @@
     LinodeModuleBase,
 )
 from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
+    BETA_DISCLAIMER,
     global_authors,
     global_requirements,
 )
@@ -53,6 +54,7 @@ def __init__(
         params: List[ListModuleParam] = None,
         examples: List[str] = None,
         result_samples: List[str] = None,
+        requires_beta: bool = False,
     ) -> None:
         self.result_display_name = result_display_name
         self.result_field_name = result_field_name
@@ -62,6 +64,7 @@ def __init__(
         self.params = params or []
         self.examples = examples or []
         self.result_samples = result_samples or []
+        self.requires_beta = requires_beta
 
         self.module_arg_spec = self.spec.ansible_spec
         self.results: Dict[str, Any] = {self.result_field_name: []}
@@ -153,8 +156,13 @@ def spec(self):
                 required=True,
             )
 
+        description = [f"List and filter on {self.result_display_name}s."]
+
+        if self.requires_beta:
+            description.append(BETA_DISCLAIMER)
+
         return SpecDocMeta(
-            description=[f"List and filter on {self.result_display_name}s."],
+            description=description,
             requirements=global_requirements,
             author=global_authors,
             options=options,

plugins/module_utils/linode_docs.py

@@ -9,3 +9,8 @@
 ]
 
 global_requirements = ["python >= 3"]
+
+BETA_DISCLAIMER = (
+    "**:warning: This module makes use of beta endpoints and requires the `api_version` "
+    "field be explicitly set to `v4beta`.**"
+)

plugins/modules/account_availability_info.py

@@ -35,6 +35,7 @@
             )._raw_json,
         ),
     ],
+    requires_beta=True,
 )
 
 SPECDOC_META = module.spec

plugins/modules/account_availability_list.py

@@ -19,6 +19,7 @@
     result_docs_url="TBD",
     result_samples=docs.result_account_availabilities_samples,
     examples=docs.specdoc_examples,
+    requires_beta=True,
 )
 
 SPECDOC_META = module.spec

plugins/modules/ip_share.py

@@ -12,6 +12,7 @@
     LinodeModuleBase,
 )
 from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
+    BETA_DISCLAIMER,
     global_authors,
     global_requirements,
 )
@@ -44,7 +45,10 @@
 }
 
 SPECDOC_META = SpecDocMeta(
-    description=["Manage the Linode shared IPs."],
+    description=[
+        "Manage the Linode shared IPs.",
+        BETA_DISCLAIMER,
+    ],
     requirements=global_requirements,
     author=global_authors,
     options=ip_share_spec,

plugins/modules/vlan_info.py

@@ -12,6 +12,7 @@
     LinodeModuleBase,
 )
 from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
+    BETA_DISCLAIMER,
     global_authors,
     global_requirements,
 )
@@ -32,7 +33,10 @@
 }
 
 SPECDOC_META = SpecDocMeta(
-    description=["Get info about a Linode VLAN."],
+    description=[
+        "Get info about a Linode VLAN.",
+        BETA_DISCLAIMER,
+    ],
     requirements=global_requirements,
     author=global_authors,
     options=linode_vlan_info_spec,

plugins/modules/vlan_list.py

@@ -12,6 +12,7 @@
     LinodeModuleBase,
 )
 from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
+    BETA_DISCLAIMER,
     global_authors,
     global_requirements,
 )
@@ -76,7 +77,10 @@
 }
 
 SPECDOC_META = SpecDocMeta(
-    description=["List and filter on Linode VLANs."],
+    description=[
+        "List and filter on Linode VLANs.",
+        BETA_DISCLAIMER,
+    ],
     requirements=global_requirements,
     author=global_authors,
     options=spec,

pyproject.toml

@@ -44,6 +44,7 @@ disable = [
     "duplicate-code",
     "too-many-lines",
     "too-many-branches",
+    "too-many-instance-attributes",
     "anomalous-backslash-in-string",
     "too-many-locals",
     "consider-using-f-string",