proxmox_subnet: Added docs

- Also fix sanity issues

Author: JanaHoch

plugins/modules/proxmox_subnet.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-
+#
 # Copyright (c) 2025, Jana Hoch <[email protected]>
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
@@ -9,13 +9,151 @@
 
 __metaclass__ = type
 
-from pygments.lexer import default
-
-DOCUMENTATION = r""""""
-
-EXAMPLES = r""""""
-
-RETURN = r""""""
+DOCUMENTATION = r"""
+module: proxmox_subnet
+short_description: Create/Update/Delete subnets from SDN
+description:
+  - Create, update, or delete subnets in Proxmox SDN.
+author: 'Jana Hoch <[email protected]> (!UNKNOWN)'
+attributes:
+  check_mode:
+    support: none
+  diff_mode:
+    support: none
+options:
+  state:
+    description:
+      - Desired state of the network configuration.
+      - Choices include present (create), absent (delete), or update (modify).
+    type: str
+    choices: ['present', 'absent', 'update']
+    default: present
+  force:
+    description:
+      - If true it will create subnet when state is update but subnet is missing and update the subnet when state is present and subnet already exists
+    type: bool
+    default: False
+  subnet:
+    description:
+      - subnet CIDR.
+    type: str
+    required: true
+  type:
+    description:
+      - Type of network configuration.
+      - Currently only supports 'subnet'.
+    type: str
+    choices: ['subnet']
+    default: subnet
+  vnet:
+    description:
+      - The virtual network to which the subnet belongs.
+    type: str
+    required: true
+  zone:
+    description:
+      - Vnet Zone
+    type: str
+  dhcp_dns_server:
+    description:
+      - IP address for the DNS server.
+    type: str
+  dhcp_range:
+    description:
+      - Range of IP addresses for DHCP.
+    type: list
+    elements: dict
+    suboptions:
+      start:
+        description:
+          - Starting IP address of the DHCP range.
+        type: str
+        required: true
+      end:
+        description:
+          - Ending IP address of the DHCP range.
+        type: str
+        required: true
+  dnszoneprefix:
+    description:
+      - Prefix for the DNS zone.
+    type: str
+  gateway:
+    description:
+      - Subnet Gateway. Will be assign on vnet for layer3 zones.
+    type: str
+  lock_token:
+    description:
+      - the token for unlocking the global SDN configuration.
+    type: str
+  snat:
+    description:
+      - Enable Source NAT for the subnet.
+    type: bool
+    default: False
+  delete:
+    description:
+      - A list of settings you want to delete.
+    type: str
+extends_documentation_fragment:
+  - community.proxmox.proxmox.actiongroup_proxmox
+  - community.proxmox.proxmox.documentation
+  - community.proxmox.attributes
+"""
+
+EXAMPLES = r"""
+- name: Create a subnet
+  community.proxmox.proxmox_subnet:
+    api_user: "{{ pc.proxmox.api_user }}"
+    api_token_id: "{{ pc.proxmox.api_token_id }}"
+    api_token_secret: "{{ vault.proxmox.api_token_secret }}"
+    api_host: "{{ pc.proxmox.api_host }}"
+    validate_certs: no
+    vnet: test
+    subnet: 10.10.2.0/24
+    zone: ans1
+    state: present
+
+- name: Update a subnet
+  community.proxmox.proxmox_subnet:
+    api_user: "{{ pc.proxmox.api_user }}"
+    api_token_id: "{{ pc.proxmox.api_token_id }}"
+    api_token_secret: "{{ vault.proxmox.api_token_secret }}"
+    api_host: "{{ pc.proxmox.api_host }}"
+    validate_certs: no
+    vnet: test
+    subnet: 10.10.2.0/24
+    zone: ans1
+    state: update
+    dhcp_range:
+      - start: 10.10.2.5
+        end: 10.10.2.50
+      - start: 10.10.2.100
+        end: 10.10.2.150
+    snat: True
+
+- name: Delete a subnet
+  community.proxmox.proxmox_subnet:
+    api_user: "{{ pc.proxmox.api_user }}"
+    api_token_id: "{{ pc.proxmox.api_token_id }}"
+    api_token_secret: "{{ vault.proxmox.api_token_secret }}"
+    api_host: "{{ pc.proxmox.api_host }}"
+    validate_certs: no
+    vnet: test
+    subnet: 10.10.2.0/24
+    zone: ans1
+    state: absent
+"""
+
+RETURN = r"""
+subnet:
+  description:
+    - Subnet ID which was created/updated/deleted
+  returned: on success
+  type: str
+  sample:
+    ans1-10.10.2.0-24
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.community.proxmox.plugins.module_utils.proxmox import (
@@ -24,6 +162,7 @@
     ProxmoxAnsible
 )
 
+
 def get_proxmox_args():
     return dict(
         state=dict(type="str", choices=["present", "absent", "update"], default='present', required=False),
@@ -44,11 +183,12 @@ def get_proxmox_args():
         ),
         dnszoneprefix=dict(type='str', required=False),
         gateway=dict(type='str', required=False),
-        lock_token=dict(type="str", required=False),
+        lock_token=dict(type="str", required=False, no_log=False),
         snat=dict(type='bool', default=False, required=False),
         delete=dict(type="str", required=False)
     )
 
+
 def get_ansible_module():
     module_args = proxmox_auth_argument_spec()
     module_args.update(get_proxmox_args())
@@ -62,6 +202,7 @@ def get_ansible_module():
         ]
     )
 
+
 class ProxmoxSubnetAnsible(ProxmoxAnsible):
     def __init__(self, module):
         super(ProxmoxSubnetAnsible, self).__init__(module)
@@ -96,7 +237,7 @@ def get_dhcp_range(self):
         dhcp_range = [f"start-address={x['start']},end-address={x['end']}" for x in self.params.get('dhcp_range')]
         return dhcp_range
 
-    def subnet_present(self,force, **subnet_params):
+    def subnet_present(self, force, **subnet_params):
         vnet_name = subnet_params['vnet']
         lock = subnet_params['lock-token']
         subnet = subnet_params['subnet']
@@ -123,10 +264,10 @@ def subnet_present(self,force, **subnet_params):
         except Exception as e:
             self.rollback_sdn_changes_and_release_lock(lock=lock)
             self.module.fail_json(
-                msg=f'Failed to create subnet. Rolling back all changes. : {e}'
+                msg=f'Failed to create subnet. Rolling back all changes : {e}'
             )
 
-    def subnet_update(self,force, **subnet_params):
+    def subnet_update(self, force, **subnet_params):
         lock = subnet_params['lock-token']
         vnet_id = subnet_params['vnet']
         subnet_id = f"{self.params['zone']}-{subnet_params['subnet'].replace('/', '-')}"