From 5dd5faccb09cc11fb60dd12c4fe2640455893753 Mon Sep 17 00:00:00 2001
From: Thomas Woerner <twoerner@redhat.com>
Date: Tue, 23 Jul 2019 10:01:59 +0200
Subject: [PATCH] New utils script to update module docs
Usage: sh utils/gen_modules_docs.sh
---
utils/gen_module_docs.py | 309 ++++++++++++++++++++++++++++++++++++++
utils/gen_modules_docs.sh | 3 +
2 files changed, 312 insertions(+)
create mode 100644 utils/gen_module_docs.py
create mode 100644 utils/gen_modules_docs.sh
diff --git a/utils/gen_module_docs.py b/utils/gen_module_docs.py
new file mode 100644
index 00000000..9ebd6f5e
--- /dev/null
+++ b/utils/gen_module_docs.py
@@ -0,0 +1,309 @@
+import os
+import sys
+import re
+
+param_docs = {
+ "ccache": "The local ccache",
+ "installer_ccache": "The installer ccache setting",
+ "_top_dir": "The installer _top_dir setting",
+ "_ca_enabled": "The installer _ca_enabled setting",
+ "_add_to_ipaservers": "The installer _add_to_ipaservers setting",
+ "_ca_subject": "The installer _ca_subject setting",
+ "_subject_base": "The installer _subject_base setting",
+ "config_setup_ca": "The config setup_ca setting",
+ "config_master_host_name": "The config master_host_name setting",
+ "config_ca_host_name": "The config ca_host_name setting",
+ "config_ips": "The config ips setting",
+ "_ca_file": "The installer _ca_file setting",
+ "_kra_enabled": "The installer _kra_enabled setting",
+ "_dirsrv_pkcs12_info": "The installer _dirsrv_pkcs12_info setting",
+ "_pkinit_pkcs12_info": "The installer _pkinit_pkcs12_info setting",
+ "_http_pkcs12_info": "The installer _http_pkcs12_info setting",
+ "ds_ca_subject": "The ds.ca_subject setting",
+ "ca_subject": "The installer ca_subject setting",
+ "_hostname_overridden": "The installer _hostname_overridden setting",
+ "_kra_host_name": "The installer _kra_host_name setting",
+ "_http_ca_cert": "The installer _http_ca_cert setting",
+ "_update_hosts_file": "The installer _update_host_file setting",
+ "sssd": "The installer sssd setting",
+ "dnsok": "The installer dnsok setting",
+
+ "dm_password": "Directory Manager password",
+ "password": "Admin user kerberos password",
+ "ip_addresses": "List of Master Server IP Addresses",
+ "domain": "Primary DNS domain of the IPA deployment",
+ "realm": "Kerberos realm name of the IPA deployment",
+ "hostname": "Fully qualified name of this host",
+ "ca_cert_file": [
+ "A CA certificate to use. Do not acquire the IPA CA certificate via",
+ "automated means"
+ ],
+ "ca_cert_files": [
+ "List of files containing CA certificates for the service certificate",
+ "files"
+ ],
+ "no_host_dns": "Do not use DNS for hostname lookup during installation",
+ "setup_adtrust": "Configure AD trust capability",
+ "setup_ca": "Configure a dogtag CA",
+ "setup_kra": "Configure a dogtag KRA",
+ "setup_dns": "Configure bind with our zone",
+ "dirserv_cert_files": [
+ "File containing the Directory Server SSL certificate and private key"
+ ],
+ "force_join": "Force client enrollment even if already enrolled",
+ "subject_base": [
+ "The certificate subject base (default O=<realm-name>).",
+ "RDNs are in LDAP order (most specific RDN first)."
+ ],
+ "server": "Fully qualified name of IPA server to enroll to",
+ "dirman_password": "Directory Manager (master) password",
+ "no_pkinit": "Disable pkinit setup steps",
+ "no_ui_redirect": "Do not automatically redirect to the Web UI",
+ "external_ca": "External ca setting",
+ "setup_adtrust": "Configure AD trust capability",
+ "external_cert_files": [
+ "File containing the IPA CA certificate and the external CA certificate",
+ "chain"
+ ],
+ "reverse_zones": "The reverse DNS zones to use",
+ "no_reverse": "Do not create new reverse DNS zone",
+ "auto_reverse": "Create necessary reverse zones",
+ "forwarders": "Add DNS forwarders",
+ "no_forwarders": "Do not add any DNS forwarders, use root servers instead",
+ "auto_forwarders": "Use DNS forwarders configured in /etc/resolv.conf",
+ "forward_policy": "DNS forwarding policy for global forwarders",
+ "enable_compat": "Enable support for trusted domains for old clients",
+ "netbios_name": "NetBIOS name of the IPA domain",
+ "rid_base": "Start value for mapping UIDs and GIDs to RIDs",
+ "secondary_rid_base": [
+ "Start value of the secondary range for mapping UIDs and GIDs to RIDs"
+ ],
+ "pki_config_override": "Path to ini file with config overrides",
+ "servers": "Fully qualified name of IPA servers to enroll to",
+ "hidden_replica": "Install a hidden replica",
+ "dirsrv_config_file": [
+ "The path to LDIF file that will be used to modify configuration of",
+ "dse.ldif during installation of the directory server instance"
+ ],
+ "dirsrv_cert_files": [
+ "Files containing the Directory Server SSL certificate and private key"
+ ],
+ "http_cert_files": [
+ "File containing the Apache Server SSL certificate and private key"
+ ],
+ "pkinit_cert_files": [
+ "File containing the Kerberos KDC SSL certificate and private key"
+ ],
+ "no_ntp": "Do not configure ntp",
+ "ntp_servers": "ntp servers to use",
+ "ntp_pool": "ntp server pool to use",
+ "no_dnssec_validation": "Disable DNSSEC validation",
+ "master": "Master host name",
+ "master_password": "kerberos master password (normally autogenerated)",
+ "principal": [
+ "User Principal allowed to promote replicas and join IPA realm"
+ ],
+ "dirsrv_pin": "The password to unlock the Directory Server private key",
+ "http_pin": "The password to unlock the Apache Server private key",
+ "pkinit_pin": "The password to unlock the Kerberos KDC private key",
+ "dirsrv_cert_name": "Name of the Directory Server SSL certificate to install",
+ "http_cert_name": "Name of the Apache Server SSL certificate to install",
+ "pkinit_cert_name": "Name of the Kerberos KDC SSL certificate to install",
+ "keytab": "Path to backed up keytab from previous enrollment",
+ "mkhomedir": "Create home directories for users on their first login",
+ "adtrust_netbios_name": "The adtrust netbios_name setting",
+ "adtrust_reset_netbios_name": "The adtrust reset_netbios_name setting",
+ "zonemgr": "DNS zone manager e-mail address. Defaults to hostmaster@DOMAIN",
+ "ssh_trust_dns": "Configure OpenSSH client to trust DNS SSHFP records",
+ "dns_ip_addresses": "The dns ip_addresses setting",
+ "dns_reverse_zones": "The dns reverse_zones setting",
+ "no_ssh": "Do not configure OpenSSH client",
+ "no_sshd": "Do not configure OpenSSH server",
+ "no_dns_sshfp": "Do not automatically create DNS SSHFP records",
+ "allow_zone_overlap": "Create DNS zone even if it already exists",
+ "skip_conncheck": "Skip connection check to remote master",
+ "idstart": "The starting value for the IDs range (default random)",
+ "idmax": "The max value for the IDs range (default: idstart+199999)",
+ "no_hbac_allow": "Don't install allow_all HBAC rule",
+ "domainlevel": "The domain level",
+ "external_ca_type": "Type of the external CA",
+ "external_ca_profile": [
+ "Specify the certificate profile/template to use at the external CA"
+ ],
+ "force": "Installer force parameter",
+ "ca_signing_algorithm": "Signing algorithm of the IPA CA certificate",
+ "debug": "Turn on extra debugging",
+ "basedn": "The basedn of the IPA server (of the form dc=example,dc=com)",
+ "allow_repair": [
+ "Allow repair of already joined hosts. Contrary to ipaclient_force_join",
+ "the host entry will not be changed on the server"
+ ],
+ "backup": "File to backup",
+ "fqdn": [
+ "The fully-qualified hostname of the host to add/modify/remove"
+ ],
+ "certificates": "A list of host certificates",
+ "sshpubkey": "The SSH public key for the host",
+ "ipaddress": "The IP address for the host",
+ "random": "Generate a random password to be used in bulk enrollment",
+ "state": "The desired host state",
+ "kdc": "The name or address of the host running the KDC",
+ "admin_keytab": "The path to a local admin keytab",
+ "kinit_attempts": "Repeat the request for host Kerberos ticket X times",
+ "automount_location": "The automount location",
+ "firefox_dir": [
+ "Specify directory where Firefox is installed (for example",
+ "'/usr/lib/firefox')"
+ ],
+ "client_domain": "Primary DNS domain of the IPA deployment",
+ "nisdomain": "The NIS domain name",
+ "ca_enabled": "Whether the Certificate Authority is enabled or not",
+ "on_master": "Whether the configuration is done on the master or not",
+ "enable_dns_updates": [
+ "Configures the machine to attempt dns updates when the ip address",
+ "changes"
+ ],
+ "all_ip_addresses": [
+ "All routable IP addresses configured on any interface will be added",
+ "to DNS"
+ ],
+ "request_cert": "Request certificate for the machine",
+ "preserve_sssd": "Preserve old SSSD configuration if possible",
+ "no_sudo": "Do not configure SSSD as data source for sudo",
+ "fixed_primary": "Configure sssd to use fixed server as primary IPA server",
+ "permit": "Disable access rules by default, permit all access",
+ "no_krb5_offline_passwords": [
+ "Configure SSSD not to store user password when the server is offline"
+ ],
+ "force_ntpd": [
+ "Stop and disable any time&date synchronization services besides ntpd",
+ "Deprecated since 4.7"
+ ],
+ "no_nisdomain": "Do not configure NIS domain name",
+ "configure_firefox": "Configure Firefox to use IPA domain credentials",
+}
+
+
+def gen_module_docs(module_in):
+ lines = [ ]
+
+ with open(module_in) as in_f:
+ in_lines = in_f.readlines()
+
+ arg_spec = False
+ args = []
+ i = 0
+ while i < len(in_lines):
+ line = in_lines[i]
+ stripped = line.strip()
+ #print("stripped: %s" % repr(stripped))
+ if stripped.startswith("# "):
+ pass
+ elif stripped.startswith("argument_spec=dict()"):
+ pass
+ elif stripped.startswith("argument_spec=dict("):
+ arg_spec = True
+ elif stripped.startswith("),") and arg_spec:
+ arg_spec = False
+ elif arg_spec:
+ #if not "dict=(" in stripped:
+ # print("%s: Bad argument dict line '%s'" % (module_in,
+ # stripped))
+ while ")," not in stripped and i < len(in_lines) - 1:
+ next_stripped = in_lines[i+1].strip()
+ if not next_stripped.startswith("# "):
+ stripped += next_stripped
+ i += 1
+ #print("stripped: '%s'" % stripped)
+
+ try:
+ param, _dict = stripped.split("=", 1)
+ except:
+ print("Failed to split line '%s'" % stripped)
+ sys.exit(1)
+
+ #print("_dict: '%s'" % _dict)
+ if not _dict.startswith("dict(") or not _dict.endswith("),"):
+ print("%s: Bad argument dict line 2 '%s'" % (module_in, _dict))
+ sys.exit(1)
+ else:
+ _dict = _dict[5:-2]
+
+ if param not in param_docs:
+ print("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!")
+ print("%s: param '%s' is not in param_docs" % (module_in, param))
+ print("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!")
+ sys.exit(1)
+
+ #print("param: '%s', dict: '%s'" % (param, _dict))
+
+ opts = _dict.split(',')
+ opts = [ o.strip() for o in opts ]
+ required = False
+ #no_log = False
+ if "required=True" in opts:
+ required = True
+ #if "no_log=True" in opts:
+ # no_log = True
+
+ #args.append([param, required, no_log])
+ args.append([param, required])
+ i += 1
+
+ #print("%s: %s" % (module_in, repr(args)))
+
+ def add_options(args):
+ for param, required in args:
+ out_lines.append(" %s:\n" % param)
+ if isinstance(param_docs[param], list):
+ out_lines.append(" description:\n")
+ for x in param_docs[param]:
+ out_lines.append(" %s\n" % x)
+ else:
+ out_lines.append(" description: %s\n" % param_docs[param])
+ out_lines.append(" required: %s\n" % ("yes","no")[required])
+
+ out_lines = []
+ options = False
+ in_options = False
+ changed = False
+ docs = False
+ for line in in_lines:
+ stripped = line.strip()
+ if stripped.startswith("DOCUMENTATION = '''"):
+ docs = True
+ elif stripped.startswith("options:"):
+ out_lines.append(line)
+ add_options(args)
+ options = True
+ in_options = True
+ changed = True
+ continue
+ elif stripped.startswith("author:"):
+ if not options:
+ add_options(args)
+ options = True
+ changed = True
+ in_options = False
+ elif stripped.startswith("'''"):
+ if not options:
+ add_options(args)
+ options = True
+ changed = True
+ in_options = False
+ docs = False
+ elif docs and in_options:
+ continue
+
+ out_lines.append(line)
+
+ print(module_in)
+ #for line in out_lines:
+ # sys.stdout.write(line)
+
+ if changed:
+ with open(module_in, "w") as out_f:
+ for line in out_lines:
+ out_f.write(line)
+
+gen_module_docs(sys.argv[1])
diff --git a/utils/gen_modules_docs.sh b/utils/gen_modules_docs.sh
new file mode 100644
index 00000000..de1d9319
--- /dev/null
+++ b/utils/gen_modules_docs.sh
@@ -0,0 +1,3 @@
+for i in roles/ipa*/*/*.py; do
+ python utils/gen_module_docs.py $i
+done
--
GitLab