Inject documentation before release using ansible-specdoc (#537)

* adding stubs for doc injection

* stub missing files

* add quotes around range

* remove debug echo

* update docs and add inject-clean

* make format

* line too long

* updating to rich text

* add sanity check

* update specdoc

.github/workflows/release.yml

@@ -35,6 +35,9 @@ jobs:
       - name: install ansible dependencies
         run: ansible-galaxy collection install amazon.aws:==6.0.1
 
+      - name: inject docs using specdoc
+        run: make inject
+
       - name: publish the collection
         run: make publish
         env:

Makefile

@@ -105,3 +105,12 @@ endif
 	@echo "api_url: $(TEST_API_URL)" >> $(INTEGRATION_CONFIG)
 	@echo "api_version: $(TEST_API_VERSION)" >> $(INTEGRATION_CONFIG)
 	@echo "ca_file: $(TEST_API_CA)" >> $(INTEGRATION_CONFIG)
+
+inject:
+	@echo "Injecting documentation into source files"
+	for f in `ls ./plugins/modules/*.py`; do ansible-specdoc -j -i $$f; done
+	ansible-test sanity --test ansible-doc
+
+inject-clean:
+	@echo "Removing injected documentation from source files"
+	for f in `ls ./plugins/modules/*.py`; do ansible-specdoc -jc -i $$f; done

docs/modules/ipv6_range_info.md

@@ -17,7 +17,7 @@ Get info about a Linode IPv6 range.
 ```yaml
 - name: Get info about an IPv6 range
   linode.cloud.ipv6_range_info:
-    range: 2600:3c01::
+    range: "2600:3c01::"
 ```
 
 

plugins/module_utils/doc_fragments/ipv6_range_info.py

@@ -3,7 +3,7 @@
 specdoc_examples = ['''
 - name: Get info about an IPv6 range
   linode.cloud.ipv6_range_info:
-    range: 2600:3c01::''']
+    range: "2600:3c01::"''']
 
 
 result_range_samples = ['''{

plugins/modules/account_availability_info.py

@@ -40,5 +40,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/account_availability_list.py

@@ -24,5 +24,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/account_info.py

@@ -44,6 +44,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode Account"""

plugins/modules/api_request.py

@@ -87,6 +87,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for running arbitrary Linode API requests"""

plugins/modules/child_account_info.py

@@ -44,5 +44,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/child_account_list.py

@@ -29,5 +29,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/database_engine_list.py

@@ -98,6 +98,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting a list of Managed Database engine types"""

plugins/modules/database_list.py

@@ -97,6 +97,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode databases"""

plugins/modules/database_mysql.py

@@ -172,6 +172,13 @@
 
 MUTABLE_FIELDS = {"allow_list", "updates"}
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for creating and destroying Linode Databases"""

plugins/modules/database_mysql_info.py

@@ -90,6 +90,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode user"""

plugins/modules/database_postgresql.py

@@ -184,6 +184,13 @@
 
 MUTABLE_FIELDS = {"allow_list", "updates"}
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for creating and destroying Linode Databases"""

plugins/modules/database_postgresql_info.py

@@ -90,6 +90,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode PostgreSQL database"""

plugins/modules/domain.py

@@ -175,6 +175,13 @@
     "group",
 }
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeDomain(LinodeModuleBase):
     """Module for creating and destroying Linode Domains"""

plugins/modules/domain_info.py

@@ -82,6 +82,13 @@
 
 linode_domain_valid_filters = ["id", "domain"]
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeDomainInfo(LinodeModuleBase):
     """Module for getting info about a Linode Domain"""

plugins/modules/domain_list.py

@@ -93,6 +93,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting a list of domains"""

plugins/modules/domain_record.py

@@ -158,6 +158,13 @@
     "weight",
 }
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeDomainRecord(LinodeModuleBase):
     """Module for creating and destroying Linode Domain records"""

plugins/modules/domain_record_info.py

@@ -85,6 +85,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeDomainRecordInfo(LinodeModuleBase):
     """Module for getting info about a Linode Domain record"""

plugins/modules/event_list.py

@@ -92,6 +92,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode events"""

plugins/modules/firewall.py

@@ -191,6 +191,13 @@
 # Fields that can be updated on an existing Firewall
 MUTABLE_FIELDS: List[str] = ["status", "tags"]
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeFirewall(LinodeModuleBase):
     """Module for creating and destroying Linode Firewalls"""

plugins/modules/firewall_device.py

@@ -72,6 +72,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeFirewallDevice(LinodeModuleBase):
     """Module for managing Linode Firewall devices"""

plugins/modules/firewall_info.py

@@ -72,6 +72,13 @@
 
 linode_firewall_valid_filters = ["id", "label"]
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeFirewallInfo(LinodeModuleBase):
     """Module for viewing info about a Linode Firewall"""

plugins/modules/firewall_list.py

@@ -94,6 +94,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting a list of Firewalls"""

plugins/modules/image.py

@@ -110,6 +110,13 @@
 
 MUTABLE_FIELDS = {"description"}
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for creating and destroying Linode Images"""

plugins/modules/image_info.py

@@ -58,6 +58,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode user"""

plugins/modules/image_list.py

@@ -21,5 +21,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/instance.py

@@ -570,6 +570,13 @@
     "interfaces",
 }
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class LinodeInstance(LinodeModuleBase):
     """Module for creating and destroying Linode Instances"""