cloud-init schema --docs is no longer useful

[TheRealFalcon]

cloud-init schema --docs used to output something similar to our modules docs, but since a recent refactor (plus some follow-up PRs), we only get the docstrings of the python modules in a format that is unreadable:

root@me:~# cloud-init schema --docs all
ansible enables running on first boot either ansible-pullApk Configure: Configures apk repositories file.Apt Configure: Configure apt for the user.Apt Pipelining: configure apt pipelining.Bootcmd: run arbitrary commands early in the boot process.Byobu: Enable/disable byobu system wide and for default user.CA Certs: Add ca certificates.Chef: module that configures, starts and installs chef.Disable EC2 Metadata: Disable AWS EC2 metadata.Disk Setup: Configure partitions and filesystems.Fan: Configure ubuntu fan networkingFinal Message: Output final message when cloud-init has finishedGrowpart: Grow partitionsGrub Dpkg: Configure grub debconf installation deviceInstall hotplug udev rules if supported and enabledkeyboard: set keyboard layoutKeys to Console: Control which SSH host keys may be written to consoleinstall and configure landscape clientLocale: set system localeLXD: configure lxd with ``lxd init`` and optionally lxd-bridgeMcollective: Install, configure and start mcollectiveMounts: Configure mount points and swap filesNTP: enable and configure ntpPackage Update Upgrade Install: update, upgrade, and install packagesPhone Home: Post data to urlPower State Change: Change power statePuppet: Install, configure and start puppetResizefs: cloud-config module which resizes the filesystemResolv Conf: configure resolv.confRed Hat Subscription: Register Red Hat Enterprise Linux based systemRsyslog: Configure system logging via rsyslogRuncmd: run arbitrary commands at rc.local with output to the consoleSalt Minion: Setup and run salt minionScripts Per Boot: Run per boot scriptsScripts Per Instance: Run per instance scriptsScripts Per Once: Run one time scriptsScripts User: Run user scriptsScripts Vendor: Run vendor scriptsSeed Random: Provide random seed dataSet Hostname: Set hostname and FQDNSet Passwords: Set user passwords and enable/disable SSH password authSnap: Install, configure and manage snapd and snap packages.Spacewalk: Install and configure spacewalkSSH: Configure SSH and SSH keysSSH AuthKey Fingerprints: Log fingerprints of user SSH keysSSH Import ID: Import SSH idTimezone: Set the system timezoneAutoinstall: Support ubuntu live-server autoinstall syntax.Ubuntu Drivers: Interact with third party drivers in Ubuntu.ubuntu_pro: Configure Ubuntu Pro support servicesUpdate Etc Hosts: Update the hosts file (usually ``/etc/hosts``)Update Hostname: Update hostname and fqdnUsers and Groups: Configure users and groupsWireguardWrite Files: write arbitrary filesWrite Files Deferred: Defer writing certain filesYum Add Repo: Add yum repository configuration to the systemzypper_add_repo: Add zypper repositories to the system

[TheRealFalcon]

I'm in favor of removing the cloud-init schema --docs command entirely. The documentation is a few clicks away and I don't think it's reasonable to expect full module documentation on the CLI.

The alternative is to ship the module docs in the cloud-init package and then update the parsing to use those rather than the old-style doc generation.

[holmanb]

It is broken, and its benefit was marginal, so I'm not sure that a fix would be worth it.

Anybody that wants docs locally can always just do something like: git clone ...; tox -e doc; xdg-open doc/rtd_html/index.html

[blackboxsw]

While I don't think generally that we can expect folks to have git available in their environment and all dependencies to perform tox -e doc, I do agree with both of your sentiments. This schema generation on the command line has marginal value. It has exactly the same canned/simple examples that we render in our upstream docs at https://cloudinit.readthedocs.io/en/latest/reference/modules.html. For anyone wanting local examples of cloud-config files, we still do include such static examples in our cloud-init package in /usr/share/doc/cloud-init/examples . For more details, context or updates, the online documentation is probably the best source of truth for latest module-specific examples anyway.