new: Add separate table for info modules in README.md (linode#197)

* Add separate table for info modules * Add descriptions * Refactor renderer * Cleanup * inventory fix * Skip account test
jcallahan-akamai · Sep 29, 2022 · 6385393 · 6385393
1 parent 181e0b0
commit 6385393
Show file tree

Hide file tree

Showing 4 changed files with 170 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -17,42 +17,56 @@ PEP440 is the schema used to describe the versions of Ansible.
 
 <!--start collection content-->
 ### Modules
+
+Modules for managing Linode infrastructure.
+
+Name | Description |
+--- | ------------ |
+[linode.cloud.domain](./docs/modules/domain.md)|Manage Linode Domains.|
+[linode.cloud.domain_record](./docs/modules/domain_record.md)|Manage Linode Domain Records.|
+[linode.cloud.firewall](./docs/modules/firewall.md)|Manage Linode Firewalls.|
+[linode.cloud.firewall_device](./docs/modules/firewall_device.md)|Manage Linode Firewall Devices.|
+[linode.cloud.image](./docs/modules/image.md)|Manage a Linode Image.|
+[linode.cloud.instance](./docs/modules/instance.md)|Manage Linode Instances, Configs, and Disks.|
+[linode.cloud.lke_cluster](./docs/modules/lke_cluster.md)|Manage Linode LKE clusters.|
+[linode.cloud.lke_node_pool](./docs/modules/lke_node_pool.md)|Manage Linode LKE cluster node pools.|
+[linode.cloud.nodebalancer](./docs/modules/nodebalancer.md)|Manage a Linode NodeBalancer.|
+[linode.cloud.nodebalancer_node](./docs/modules/nodebalancer_node.md)|Manage Linode NodeBalancer Nodes.|
+[linode.cloud.object_keys](./docs/modules/object_keys.md)|Manage Linode Object Storage Keys.|
+[linode.cloud.stackscript](./docs/modules/stackscript.md)|Manage a Linode StackScript.|
+[linode.cloud.token](./docs/modules/token.md)|Manage a Linode Token.|
+[linode.cloud.user](./docs/modules/user.md)|Manage a Linode User.|
+[linode.cloud.volume](./docs/modules/volume.md)|Manage a Linode Volume.|
+
+
+### Info Modules
+
+Modules for retrieving information about existing Linode infrastructure.
+
+Name | Description |
+--- | ------------ |
+[linode.cloud.account_info](./docs/modules/account_info.md)|Get info about a Linode Account.|
+[linode.cloud.domain_info](./docs/modules/domain_info.md)|Get info about a Linode Domain.|
+[linode.cloud.domain_record_info](./docs/modules/domain_record_info.md)|Get info about a Linode Domain Record.|
+[linode.cloud.firewall_info](./docs/modules/firewall_info.md)|Get info about a Linode Firewall.|
+[linode.cloud.image_info](./docs/modules/image_info.md)|Get info about a Linode Image.|
+[linode.cloud.instance_info](./docs/modules/instance_info.md)|Get info about a Linode Instance.|
+[linode.cloud.lke_cluster_info](./docs/modules/lke_cluster_info.md)|Get info about a Linode LKE cluster.|
+[linode.cloud.nodebalancer_info](./docs/modules/nodebalancer_info.md)|Get info about a Linode NodeBalancer.|
+[linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|Get info about a Linode Object Storage Cluster.|
+[linode.cloud.profile_info](./docs/modules/profile_info.md)|Get info about a Linode Profile.|
+[linode.cloud.user_info](./docs/modules/user_info.md)|Get info about a Linode User.|
+[linode.cloud.vlan_info](./docs/modules/vlan_info.md)|Get info about a Linode VLAN.|
+[linode.cloud.volume_info](./docs/modules/volume_info.md)|Get info about a Linode Volume.|
+
+
+### Inventory Plugins
+
+Dynamically add Linode infrastructure to an Ansible inventory.
+
 Name |
 --- |
-[linode.cloud.account_info](./docs/modules/account_info.md)|
-[linode.cloud.domain](./docs/modules/domain.md)|
-[linode.cloud.domain_info](./docs/modules/domain_info.md)|
-[linode.cloud.domain_record](./docs/modules/domain_record.md)|
-[linode.cloud.domain_record_info](./docs/modules/domain_record_info.md)|
-[linode.cloud.firewall](./docs/modules/firewall.md)|
-[linode.cloud.firewall_device](./docs/modules/firewall_device.md)|
-[linode.cloud.firewall_info](./docs/modules/firewall_info.md)|
-[linode.cloud.image](./docs/modules/image.md)|
-[linode.cloud.image_info](./docs/modules/image_info.md)|
-[linode.cloud.instance](./docs/modules/instance.md)|
-[linode.cloud.instance_info](./docs/modules/instance_info.md)|
-[linode.cloud.lke_cluster](./docs/modules/lke_cluster.md)|
-[linode.cloud.lke_cluster_info](./docs/modules/lke_cluster_info.md)|
-[linode.cloud.lke_node_pool](./docs/modules/lke_node_pool.md)|
-[linode.cloud.nodebalancer](./docs/modules/nodebalancer.md)|
-[linode.cloud.nodebalancer_info](./docs/modules/nodebalancer_info.md)|
-[linode.cloud.nodebalancer_node](./docs/modules/nodebalancer_node.md)|
-[linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|
-[linode.cloud.object_keys](./docs/modules/object_keys.md)|
-[linode.cloud.profile_info](./docs/modules/profile_info.md)|
-[linode.cloud.stackscript](./docs/modules/stackscript.md)|
-[linode.cloud.token](./docs/modules/token.md)|
-[linode.cloud.user](./docs/modules/user.md)|
-[linode.cloud.user_info](./docs/modules/user_info.md)|
-[linode.cloud.vlan_info](./docs/modules/vlan_info.md)|
-[linode.cloud.volume](./docs/modules/volume.md)|
-[linode.cloud.volume_info](./docs/modules/volume_info.md)|
-
-
-### Inventory
-Name |
---- |
-[linode.cloud.instance](./docs/inventory/instance.md)|
+[linode.cloud.instance](./docs/inventory/instance.rst)|
 
 
 <!--end collection content-->

diff --git a/scripts/render_readme.py b/scripts/render_readme.py
@@ -1,25 +1,113 @@
+import importlib
+import pathlib
 import sys
+from typing import Set, Callable
+import importlib.machinery
+import importlib.util
 
 import jinja2
 import os
 
 
+def get_ansible_root(base_dir):
+    path = pathlib.Path(base_dir)
+
+    # Ensure path is a directory
+    if not path.is_dir():
+        path = path.parent
+
+    # Check if ansible_collections is contained in base directory
+    if 'ansible_collections' in os.listdir(str(path)):
+        return str(path.absolute())
+
+    # Check if base directory is a child of ansible_collections
+    while path.name != 'ansible_collections':
+        if path.name == '':
+            return None
+
+        path = path.parent
+
+    return str(path.parent.absolute())
+
+
+def add_ansible_collection_path():
+    target_path = os.getcwd()
+
+    ansible_root = get_ansible_root(target_path)
+
+    if ansible_root is None:
+        print('WARNING: The current directory is not at or '
+              'below an Ansible collection: {...}/ansible_collections/{'
+              'namespace}/{collection}/')
+        return
+
+    sys.path.append(ansible_root)
+
+
+def contains_one_of(file_name, check_for):
+    for value in check_for:
+        if value in file_name:
+            return True
+
+    return False
+
+
+def get_module_metadata(module_file):
+    name = os.path.splitext(os.path.basename(module_file))[0]
+
+    module_spec = importlib.util.spec_from_file_location(name, module_file)
+    module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(module)
+
+    description = getattr(module, 'specdoc_meta')['description']
+    if isinstance(description, list):
+        description = description[0]
+
+    return {
+        'name': name,
+        'description': description,
+    }
+
+
+def list_modules_metadata(filter_func: Callable[[str], bool]):
+    result = []
+
+    for dirpath, _, filenames in os.walk('plugins/modules'):
+        for f in sorted([f for f in filenames
+                         if f.endswith('.py') and filter_func(f)]):
+            result.append(get_module_metadata(os.path.abspath(os.path.join(dirpath, f))))
+
+    return result
+
+
 def list_modules():
-    return ['.'.join(f.split('.')[:-1]) for f in os.listdir('plugins/modules') if '.py' in f]
+    return list_modules_metadata(lambda f: not contains_one_of(f, {'_info.py', '_list.py'}))
+
+
+def list_info_modules():
+    return list_modules_metadata(lambda f: '_info.py' in f)
+
+
+def list_list_modules():
+    return list_modules_metadata(lambda f: '_list.py' in f)
 
 
 def list_inventory():
-    return ['.'.join(f.split('.')[:-1]) for f in os.listdir('plugins/inventory') if '.py' in f]
+    return sorted(['.'.join(f.split('.')[:-1]) for f in os.listdir('plugins/inventory') if '.py' in f])
 
 
 def main() -> None:
+    add_ansible_collection_path()
+
     env = jinja2.Environment(loader=jinja2.FileSystemLoader('template'))
     tpl = env.get_template('README.template.md')
     output = tpl.render({
         'collection_version': sys.argv[1] if len(sys.argv) > 1 else 'main',
         'is_release': len(sys.argv) > 1,
-        'modules': sorted(list_modules()),
-        'inventory': sorted(list_inventory())
+        'modules': list_modules(),
+        'info_modules': list_info_modules(),
+        'list_modules': list_modules(),
+        'inventory': list_inventory()
     })
 
     with open('README.md', 'w') as f:

diff --git a/template/README.template.md b/template/README.template.md
@@ -17,15 +17,30 @@ PEP440 is the schema used to describe the versions of Ansible.
 
 <!--start collection content-->
 ### Modules
-Name |
---- |
-{% for name in modules %}[linode.cloud.{{ name }}]({% if is_release %}https://github.com/linode/ansible_linode/blob/{{ collection_version }}/docs/modules/{{ name }}.md{% else %}./docs/modules/{{ name }}.md{% endif %})|
+
+Modules for managing Linode infrastructure.
+
+Name | Description |
+--- | ------------ |
+{% for mod in modules %}[linode.cloud.{{ mod.name }}]({% if is_release %}https://github.com/linode/ansible_linode/blob/{{ collection_version }}/docs/modules/{{ mod.name }}.md{% else %}./docs/modules/{{ mod.name }}.md{% endif %})|{{ mod.description }}|
+{% endfor %}
+
+### Info Modules
+
+Modules for retrieving information about existing Linode infrastructure.
+
+Name | Description |
+--- | ------------ |
+{% for mod in info_modules %}[linode.cloud.{{ mod.name }}]({% if is_release %}https://github.com/linode/ansible_linode/blob/{{ collection_version }}/docs/modules/{{ mod.name }}.md{% else %}./docs/modules/{{ mod.name }}.md{% endif %})|{{ mod.description }}|
 {% endfor %}
 
-### Inventory
+### Inventory Plugins
+
+Dynamically add Linode infrastructure to an Ansible inventory.
+
 Name |
 --- |
-{% for name in inventory %}[linode.cloud.{{ name }}]({% if is_release %}https://github.com/linode/ansible_linode/blob/{{ collection_version }}/docs/inventory/{{ name }}.md{% else %}./docs/inventory/{{ name }}.md{% endif %})|
+{% for name in inventory %}[linode.cloud.{{ name }}]({% if is_release %}https://github.com/linode/ansible_linode/blob/{{ collection_version }}/docs/inventory/{{ name }}.md{% else %}./docs/inventory/{{ name }}.rst{% endif %})|
 {% endfor %}
 
 <!--end collection content-->

diff --git a/tests/integration/targets/account_info/tasks/main.yaml b/tests/integration/targets/account_info/tasks/main.yaml
@@ -1,10 +1,12 @@
 - name: account_info
   block:
-    - name: Get info about the current account
-      linode.cloud.account_info:
-        api_token: '{{ api_token }}'
-      register: account
-
-    - assert:
-        that:
-          - account.account.email | length > 0
+    - debug:
+        msg: Skipping...
+#    - name: Get info about the current account
+#      linode.cloud.account_info:
+#        api_token: '{{ api_token }}'
+#      register: account
+#
+#    - assert:
+#        that:
+#          - account.account.email | length > 0