docs: generated summary.md (#183)

* docs: generated summary.md * doc: fix some wrong names * test new summary subcategaries * docs: improve summary * docs: update module type
ionos-cloud · Nov 3, 2023 · b20efb9 · b20efb9
1 parent 4822156
commit b20efb9
Show file tree

Hide file tree

Showing 8 changed files with 182 additions and 46 deletions.
diff --git a/docs/summary.md b/docs/summary.md
@@ -15,64 +15,127 @@
 * [Testing](usage/testing.md)
 
 ## API
-
 * Application Load Balancer
+  * Modules
+    * [Flowlog](api/applicationloadbalancer/application_load_balancer_flowlog.md)
+    * [Application Load Balancer Forwarding Rule](api/applicationloadbalancer/application_load_balancer_forwardingrule.md)
     * [Application Load Balancer](api/applicationloadbalancer/application_load_balancer.md)
-    * [Application Load Balancer Flowlog](api/applicationloadbalancer/application_load_balancer_flowlog.md)
-    * [Application Load Balancer Rule](api/applicationloadbalancer/application_load_balancer_rule.md)
-    * [Target group](api/applicationloadbalancer/target_group.md)
-* Certificate Manager
-    * [Certificate](api/certificate/certificate.md)
-    * [Certificate info](api/certificate/certificate_info.md)
+    * [Target Group](api/applicationloadbalancer/target_group.md)
+  * Info Modules
+    * [Flowlogs](api/applicationloadbalancer/application_load_balancer_flowlog_info.md)
+    * [Application Load Balancer Forwarding Rules](api/applicationloadbalancer/application_load_balancer_forwardingrule_info.md)
+    * [Application Load Balancers](api/applicationloadbalancer/application_load_balancer_info.md)
+    * [Target Groups](api/applicationloadbalancer/target_group_info.md)
 * Compute Engine
-    * [Cube template](api/compute-engine/cube_template.md)
+  * Modules
+    * [CUBE Server](api/compute-engine/cube_server.md)
     * [Datacenter](api/compute-engine/datacenter.md)
-    * [Firewall rule](api/compute-engine/firewall_rule.md)
+    * [Firewall Rule](api/compute-engine/firewall_rule.md)
     * [Image](api/compute-engine/image.md)
-    * [IpBlock](api/compute-engine/ipblock.md)
-    * [Lan](api/compute-engine/lan.md)
-    * [Nic](api/compute-engine/nic.md)
-    * [Nic Flowlog](api/compute-engine/nic_flowlog.md)
-    * [Cross connect](api/compute-engine/pcc.md)
+    * [IP Block](api/compute-engine/ipblock.md)
+    * [LAN](api/compute-engine/lan.md)
+    * [Flowlog](api/compute-engine/nic_flowlog.md)
+    * [NIC](api/compute-engine/nic.md)
+    * [PCC](api/compute-engine/pcc.md)
     * [Server](api/compute-engine/server.md)
-    * [Cube Server](api/compute-engine/cube_server.md)
     * [Snapshot](api/compute-engine/snapshot.md)
     * [Volume](api/compute-engine/volume.md)
+    * [VCPU Server](api/compute-engine/vcpu_server.md)
+  * Info Modules
+    * [CUBE templates](api/compute-engine/cube_template_info.md)
+    * [Datacenters](api/compute-engine/datacenter_info.md)
+    * [Firewall Rules](api/compute-engine/firewall_rule_info.md)
+    * [Images](api/compute-engine/image_info.md)
+    * [IpBlocks](api/compute-engine/ipblock_info.md)
+    * [Lans](api/compute-engine/lan_info.md)
+    * [Flowlogs](api/compute-engine/nic_flowlog_info.md)
+    * [NICs](api/compute-engine/nic_info.md)
+    * [PCCs](api/compute-engine/pcc_info.md)
+    * [Servers](api/compute-engine/server_info.md)
+    * [Snapshots](api/compute-engine/snapshot_info.md)
+    * [Volumes](api/compute-engine/volume_info.md)
 * Container Registry
+  * Modules
     * [Registry](api/container-registry/registry.md)
-    * [Registry Info](api/container-registry/registry_info.md)
     * [Registry Token](api/container-registry/registry_token.md)
-    * [Registry Token Info](api/container-registry/registry_token_info.md)
-* DBaaS Mongo
-    * [Mongo Cluster](api/dbaas-mongo/mongo_cluster.md)
-    * [Mongo Cluster Info](api/dbaas-mongo/mongo_cluster_info.md)
-    * [Mongo Cluster Template Info](api/dbaas-mongo/mongo_cluster_template_info.md)
+  * Info Modules
+    * [Registries](api/container-registry/registry_info.md)
+    * [Registry Tokens](api/container-registry/registry_token_info.md)
 * DBaaS Postgres
+  * Modules
     * [Postgres Cluster](api/dbaas-postgres/postgres_cluster.md)
-    * [Postgres Cluster Info](api/dbaas-postgres/postgres_cluster_info.md)
-    * [Postgres Backup Info](api/dbaas-postgres/postgres_backup_info.md)
+  * Info Modules
+    * [Postgres Cluster Backups](api/dbaas-postgres/postgres_backup_info.md)
+    * [Postgres Clusters](api/dbaas-postgres/postgres_cluster_info.md)
+* DBaaS Mongo
+  * Modules
+    * [Mongo Cluster](api/dbaas-mongo/mongo_cluster.md)
+    * [Mongo Cluster User](api/dbaas-mongo/mongo_cluster_user.md)
+  * Info Modules
+    * [Mongo Cluster Users](api/dbaas-mongo/mongo_cluster_info.md)
+    * [Mongo Cluster Templates](api/dbaas-mongo/mongo_cluster_template_info.md)
+    * [Mongo Clusters](api/dbaas-mongo/mongo_cluster_user_info.md)
 * Managed Backup
-    * [Backup unit](api/managed-backup/backupunit.md)
+  * Modules
+    * [Backup Unit](api/managed-backup/backupunit.md)
+  * Info Modules
+    * [Backupunits](api/managed-backup/backupunit_info.md)
 * Managed Kubernetes
-    * [Kubernetes cluster](api/managed-kubernetes/k8s_cluster.md)
-    * [Kubernetes nodepool](api/managed-kubernetes/k8s_nodepool.md)
-    * [Kubernetes configuration](api/managed-kubernetes/k8s_config.md)
+  * Modules
+    * [K8s Cluster](api/managed-kubernetes/k8s_cluster.md)
+    * [K8s config](api/managed-kubernetes/k8s_config.md)
+    * [K8s Nodepool](api/managed-kubernetes/k8s_nodepool.md)
+  * Info Modules
+    * [K8s Clusters](api/managed-kubernetes/k8s_cluster_info.md)
+    * [K8s Nodepools](api/managed-kubernetes/k8s_nodepool_info.md)
 * NAT Gateway
+  * Modules
+    * [Flowlog](api/natgateway/nat_gateway_flowlog.md)
+    * [NAT Gateway rule](api/natgateway/nat_gateway_rule.md)
     * [NAT Gateway](api/natgateway/nat_gateway.md)
-    * [NAT Gateway Rule](api/natgateway/nat_gateway_rule.md)
-    * [NAT Gateway Flowlog](api/natgateway/nat_gateway_flowlog.md)
+  * Info Modules
+    * [Flowlogs](api/natgateway/nat_gateway_flowlog_info.md)
+    * [NAT Gateway rules](api/natgateway/nat_gateway_rule_info.md)
+    * [NAT Gateways](api/natgateway/nat_gateway_info.md)
 * Network Load Balancer
-    * [Network Load Balancer](api/networkloadbalancer/network_load_balancer.md)
-    * [Network Load Balancer Flowlog](api/networkloadbalancer/network_load_balancer_flowlog.md)
-    * [Network Load Balancer Rule](api/networkloadbalancer/network_load_balancer_rule.md)
+  * Modules
+    * [Flowlog](api/networkloadbalancer/network_load_balancer_flowlog.md)
+    * [Network Loadbalancer forwarding rule](api/networkloadbalancer/network_load_balancer_rule.md)
+    * [Network Loadbalancer](api/networkloadbalancer/network_load_balancer.md)
+  * Info Modules
+    * [Network Loadbalancers Flowlogs](api/networkloadbalancer/network_load_balancer_flowlog_info.md)
+    * [Network Loadbalancer forwarding rules](api/networkloadbalancer/network_load_balancer_rule_info.md)
+    * [Network Loadbalancers](api/networkloadbalancer/network_load_balancer_info.md)
 * User Management
-    * [User](api/user-management/user.md)
+  * Modules
     * [Group](api/user-management/group.md)
+    * [S3 Key](api/user-management/s3key.md)
     * [Share](api/user-management/share.md)
-    * [S3key](api/user-management/s3key.md)
+    * [User](api/user-management/user.md)
+  * Info Modules
+    * [Groups](api/user-management/group_info.md)
+    * [S3 Keys](api/user-management/s3key_info.md)
+    * [Shares](api/user-management/share_info.md)
+    * [Users](api/user-management/user_info.md)
 * Data Platform
-  * [Data Platform](api/dataplatform/dataplatform_cluster.md)
-  * [Data Platform Info](api/dataplatform/dataplatform_cluster_info.md)
-  * [Data Platform Cluster Config](api/dataplatform/dataplatform_cluster_config.md)
-  * [Data Platform Nodepool](api/dataplatform/dataplatform_nodepool.md)
-  * [Data Platform Nodepool Info](api/dataplatform/dataplatform_nodepool_info.md)
+  * Modules
+    * [Data Platform Cluster](api/dataplatform/dataplatform_cluster.md)
+    * [DataPlatform Cluster Config](api/dataplatform/dataplatform_cluster_config.md)
+    * [Data Platform Nodepool](api/dataplatform/dataplatform_nodepool.md)
+  * Info Modules
+    * [DataPlatform Clusters](api/dataplatform/dataplatform_cluster_info.md)
+    * [DataPlatform Nodepools](api/dataplatform/dataplatform_nodepool_info.md)
+* Certificate Manager
+  * Modules
+    * [Certificate](api/certificate/certificate.md)
+  * Info Modules
+    * [Certificates](api/certificate/certificate_info.md)
+* Dns
+  * Modules
+    * [Zone](api/dns/dns_zone.md)
+    * [Record](api/dns/dns_record.md)
+    * [Secondary Zone](api/dns/dns_secondary_zone.md)
+  * Info Modules
+    * [DNS Zones](api/dns/dns_zone_info.md)
+    * [DNS Records](api/dns/dns_record_info.md)
+    * [DNS Secondary Zones](api/dns/dns_secondary_zone_info.md)
diff --git a/docs/templates/summary.mustache b/docs/templates/summary.mustache
@@ -0,0 +1,28 @@
+# Table of contents
+
+* [Introduction](README.md)
+* [Changelog](changelog.md)
+
+## Usage
+
+* [Authentication](usage/authentication.md)
+* [Using proxies](usage/http\_proxy.md)
+* [Ansible Playbooks](usage/ansibleplaybooks.md)
+* [Wait for Services](usage/waitforservices.md)
+* [Incrementing servers](usage/incrementingservers.md)
+* [SSH Key Authentication](usage/sshkeyauthentication.md)
+* [Return values](usage/returnvalues.md)
+* [Testing](usage/testing.md)
+
+## API
+{{#generated}}
+* {{directory_name}}
+  * Modules
+{{#modules}}
+    * [{{object_name}}]({{filename}})
+{{/modules}}
+  * Info Modules
+{{#info_modules}}
+    * [{{object_name}}]({{filename}})
+{{/info_modules}}
+{{/generated}}
diff --git a/docs_generator.py b/docs_generator.py
@@ -9,6 +9,16 @@
 EXAMPLES_DIR = os.path.join('docs', 'returned_object_examples')
 TEMPLATES_DIR = os.path.join('docs', 'templates')
 
+DIRECTORY_TO_NAME = {
+    'applicationloadbalancer': 'Application Load Balancer',
+    'certificate': 'Certificate Manager',
+    'dbaas-postgres': 'DBaaS Postgres',
+    'dbaas-mongo': 'DBaaS Mongo',
+    'natgateway': 'NAT Gateway',
+    'networkloadbalancer': 'Network Load Balancer',
+    'dataplatform': 'Data Platform',
+}
+
 
 def generate_doc_file(module, module_name, states_parameters, template_file):
     with open(os.path.join(TEMPLATES_DIR, template_file), 'r') as template_file:
@@ -80,7 +90,7 @@ def available_in_state(option):
                 'example': module.EXAMPLE_PER_STATE.get(state),
             })
         target_filename = generate_doc_file(module, module_name, parameters_per_state, 'module.mustache')
-    return module.DOC_DIRECTORY, target_filename
+    return module.DOC_DIRECTORY, target_filename, module.OBJECT_NAME
 
 modules_to_generate = [
     'application_load_balancer_flowlog_info',
@@ -170,6 +180,41 @@ def available_in_state(option):
     'dns_secondary_zone_info'
 ]
 
+generated = {}
+
 for module_name in modules_to_generate:
-    generate_module_docs(module_name)
+    docs_dir, file_name, object_name = generate_module_docs(module_name)
+
+    generated_module = {
+        'filename': file_name[5:],
+        'object_name': object_name,
+    }
+
+    directory_name = DIRECTORY_TO_NAME.get(docs_dir, docs_dir.replace('-', ' ').title())
+    if file_name.endswith('_info.md'):
+        if generated.get(directory_name):
+            generated[directory_name]['info_modules'].append(generated_module)
+        else:
+            generated[directory_name] = {
+                'directory_name': directory_name,
+                'info_modules': [generated_module],
+                'modules': [],
+        }
+    else:
+        if generated.get(directory_name):
+            generated[directory_name]['modules'].append(generated_module)
+        else:
+            generated[directory_name] = {
+                'directory_name': directory_name,
+                'info_modules': [],
+                'modules': [generated_module],
+        }
 
+with open(os.path.join('docs', 'summary.md'), 'w') as target_file:
+    with open(os.path.join(TEMPLATES_DIR, 'summary.mustache'), 'r') as template_file:
+        target_file.write(chevron.render(
+            template_file,
+            {
+                'generated': list(generated.values()),
+            },
+        ))
diff --git a/plugins/modules/application_load_balancer.py b/plugins/modules/application_load_balancer.py
@@ -33,7 +33,7 @@
 USER_AGENT = 'ansible-module/%s_ionos-cloud-sdk-python/%s' % ( __version__, sdk_version)
 DOC_DIRECTORY = 'applicationloadbalancer'
 STATES = ['present', 'absent', 'update']
-OBJECT_NAME = 'Application Loadbalancer'
+OBJECT_NAME = 'Application Load Balancer'
 RETURNED_KEY = 'application_load_balancer'
 
 OPTIONS = {

diff --git a/plugins/modules/application_load_balancer_forwardingrule.py b/plugins/modules/application_load_balancer_forwardingrule.py
@@ -42,7 +42,7 @@
 CERTIFICATE_MANAGER_USER_AGENT = 'ansible-module/%s_ionos-cloud-sdk-python/%s' % ( __version__, certificate_manager_sdk_version)
 DOC_DIRECTORY = 'applicationloadbalancer'
 STATES = ['present', 'absent', 'update']
-OBJECT_NAME = 'Application Loadbalancer forwarding rule'
+OBJECT_NAME = 'Application Load Balancer Forwarding Rule'
 RETURNED_KEY = 'forwarding_rule'
 
 OPTIONS = {

diff --git a/plugins/modules/application_load_balancer_forwardingrule_info.py b/plugins/modules/application_load_balancer_forwardingrule_info.py
@@ -22,7 +22,7 @@
 USER_AGENT = 'ansible-module/%s_ionos-cloud-sdk-python/%s' % (__version__, sdk_version)
 DOC_DIRECTORY = 'applicationloadbalancer'
 STATES = ['info']
-OBJECT_NAME = 'Application Loadbalancer forwarding rules'
+OBJECT_NAME = 'Application Load Balancer Forwarding Rules'
 RETURNED_KEY = 'forwarding_rules'
 
 OPTIONS = {

diff --git a/plugins/modules/application_load_balancer_info.py b/plugins/modules/application_load_balancer_info.py
@@ -22,7 +22,7 @@
 USER_AGENT = 'ansible-module/%s_ionos-cloud-sdk-python/%s' % (__version__, sdk_version)
 DOC_DIRECTORY = 'applicationloadbalancer'
 STATES = ['info']
-OBJECT_NAME = 'Application Loadbalancers'
+OBJECT_NAME = 'Application Load Balancers'
 RETURNED_KEY = 'application_load_balancers'
 
 OPTIONS = {

diff --git a/plugins/modules/nic_flowlog.py b/plugins/modules/nic_flowlog.py
@@ -33,7 +33,7 @@
 USER_AGENT = 'ansible-module/%s_ionos-cloud-sdk-python/%s' % (__version__, sdk_version)
 DOC_DIRECTORY = 'compute-engine'
 STATES = ['present', 'absent', 'update']
-OBJECT_NAME = 'Flowflog'
+OBJECT_NAME = 'Flowlog'
 RETURNED_KEY = 'flowlog'
 
 OPTIONS = {