From af036aa8ffa5d2e6229fdb6c0e6346976f790606 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Mon, 25 Apr 2022 15:36:32 -0600 Subject: [PATCH 1/6] Standardize punctuation, capitalization, and grammar in help text --- cloudinit/cmd/main.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/cloudinit/cmd/main.py b/cloudinit/cmd/main.py index afd0a8d81b6..bea1aff68e5 100644 --- a/cloudinit/cmd/main.py +++ b/cloudinit/cmd/main.py @@ -850,14 +850,14 @@ def main(sysv_args=None): "-f", action="append", dest="files", - help="additional yaml configuration files to use", + help="Use additional yaml configuration files.", type=argparse.FileType("rb"), ) parser.add_argument( "--debug", "-d", action="store_true", - help="show additional pre-action logging (default: %(default)s)", + help="Show additional pre-action logging (default: %(default)s).", default=False, ) parser.add_argument( @@ -877,13 +877,13 @@ def main(sysv_args=None): # Each action and its sub-options (if any) parser_init = subparsers.add_parser( - "init", help="initializes cloud-init and performs initial modules" + "init", help="Initialize cloud-init and perform initial modules" ) parser_init.add_argument( "--local", "-l", action="store_true", - help="start in local mode (default: %(default)s)", + help="Start in local mode (default: %(default)s).", default=False, ) # This is used so that we can know which action is selected + @@ -892,13 +892,13 @@ def main(sysv_args=None): # These settings are used for the 'config' and 'final' stages parser_mod = subparsers.add_parser( - "modules", help="activates modules using a given configuration key" + "modules", help="Activate modules using a given configuration key." ) parser_mod.add_argument( "--mode", "-m", action="store", - help="module configuration name to use (default: %(default)s)", + help="Module configuration name to use (default: %(default)s).", default="config", choices=("init", "config", "final"), ) @@ -918,21 +918,21 @@ def main(sysv_args=None): parser_single.add_argument( "--frequency", action="store", - help="frequency of the module", + help="Set module frequency.", required=False, choices=list(FREQ_SHORT_NAMES.keys()), ) parser_single.add_argument( "--report", action="store_true", - help="enable reporting", + help="Enable reporting.", required=False, ) parser_single.add_argument( "module_args", nargs="*", metavar="argument", - help="any additional arguments to pass to this module", + help="Any additional arguments to pass to this module.", ) parser_single.set_defaults(action=("single", main_single)) @@ -947,12 +947,12 @@ def main(sysv_args=None): dhclient_hook.get_parser(parser_dhclient) parser_features = subparsers.add_parser( - "features", help="list defined features" + "features", help="List defined features." ) parser_features.set_defaults(action=("features", main_features)) parser_analyze = subparsers.add_parser( - "analyze", help="Devel tool: Analyze cloud-init logs and data" + "analyze", help="Devel tool: Analyze cloud-init logs and data." ) parser_devel = subparsers.add_parser( @@ -960,7 +960,7 @@ def main(sysv_args=None): ) parser_collect_logs = subparsers.add_parser( - "collect-logs", help="Collect and tar all cloud-init debug info" + "collect-logs", help="Collect and tar all cloud-init debug info." ) parser_clean = subparsers.add_parser( From 317c92ad91132c09f4b412519c72db71031f5c65 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Tue, 26 Apr 2022 12:47:13 -0600 Subject: [PATCH 2/6] Man page cleanup: - standardize capitalization/grammer/punctuation - Remove cluttered subcommand list from synopsis. This is unnecessary given the total length of the document (the subcommands are all visible "above the fold", and currently the subcommands appear cluttered and doesn't look good. Also switch from "curlies" to square brackets per recommended format for optional arguments in man-pages(7) --- doc/man/cloud-init.1 | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/doc/man/cloud-init.1 b/doc/man/cloud-init.1 index 1da4335b6a4..388617de0b9 100644 --- a/doc/man/cloud-init.1 +++ b/doc/man/cloud-init.1 @@ -4,8 +4,7 @@ cloud-init \- Cloud instance initialization .SH SYNOPSIS -.BR "cloud-init" " [-h] [-d] [-f FILES] [--force] [-v] -{init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status}" +.BR "cloud-init" " [-h] [-d] [-f FILES] [--force] [-v] [SUBCOMMAND]" .SH DESCRIPTION Cloud-init provides a mechanism for cloud instance initialization. @@ -20,23 +19,23 @@ debug of deployments. .SH OPTIONS .TP .B "-h, --help" -Show help message and exit +Show help message and exit. .TP .B "-d, --debug" -Show additional pre-action logging (default: False) +Show additional pre-action logging (default: False). .TP .B "-f , --files " -Additional YAML configuration files to use +Use additional YAML configuration files. .TP .B "--force" -Force running even if no datasource is found (use at your own risk) +Force running even if no datasource is found (use at your own risk). .TP .B "-v, --version" -Show program's version number and exit +Show program's version number and exit. .SH SUBCOMMANDS Please see the help output for each subcommand for additional details, @@ -68,11 +67,11 @@ List defined features. .TP .B "init" -Initializes cloud-init and performs initial modules. +Initialize cloud-init and execute initial modules. .TP .B "modules" -Activates modules using a given configuration key. +Activate modules using a given configuration key. .TP .B "query" From 8e08c68fb82ec4d5b173cd8902c5d28769090092 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Tue, 26 Apr 2022 14:25:50 -0600 Subject: [PATCH 3/6] Add recent cloud-init content --- doc/rtd/topics/faq.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/rtd/topics/faq.rst b/doc/rtd/topics/faq.rst index e5784b717ac..0a3c8c8b509 100644 --- a/doc/rtd/topics/faq.rst +++ b/doc/rtd/topics/faq.rst @@ -313,5 +313,7 @@ variety of sources. .. _Metadata and cloud-init: https://www.youtube.com/watch?v=RHVhIWifVqU .. _The beauty of cloud-init: http://brandon.fuller.name/archives/2011/05/02/06.40.57/ .. _Introduction to cloud-init: http://www.youtube.com/watch?v=-zL3BdbKyGY +.. Blog Post: [terraform, azure, devops, docker, dotnet, cloud-init] https://codingsoul.org/2022/04/25/build-azure-devops-agents-with-linux-cloud-init-for-dotnet-development/ +.. Youtube: [proxmox, cloud-init, template] https://www.youtube.com/watch?v=shiIi38cJe4 .. vi: textwidth=79 From e6e2e093f6a1d6cc8b26c71f4a56f1ace9d46870 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Fri, 29 Apr 2022 12:39:44 -0600 Subject: [PATCH 4/6] more standardization --- cloudinit/cmd/devel/hotplug_hook.py | 10 +++++----- cloudinit/cmd/devel/make_mime.py | 2 +- cloudinit/cmd/main.py | 9 +++++---- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/cloudinit/cmd/devel/hotplug_hook.py b/cloudinit/cmd/devel/hotplug_hook.py index a9be037911d..8b66e2e6e51 100644 --- a/cloudinit/cmd/devel/hotplug_hook.py +++ b/cloudinit/cmd/devel/hotplug_hook.py @@ -1,5 +1,5 @@ # This file is part of cloud-init. See LICENSE file for license information. -"""Handle reconfiguration on hotplug events""" +"""Handle reconfiguration on hotplug events.""" import abc import argparse import os @@ -45,24 +45,24 @@ def get_parser(parser=None): subparsers.required = True subparsers.add_parser( - "query", help="query if hotplug is enabled for given subsystem" + "query", help="Query if hotplug is enabled for given subsystem." ) parser_handle = subparsers.add_parser( - "handle", help="handle the hotplug event" + "handle", help="Handle the hotplug event." ) parser_handle.add_argument( "-d", "--devpath", required=True, metavar="PATH", - help="sysfs path to hotplugged device", + help="Sysfs path to hotplugged device", ) parser_handle.add_argument( "-u", "--udevaction", required=True, - help="action to take", + help="Specify action to take.", choices=["add", "remove"], ) diff --git a/cloudinit/cmd/devel/make_mime.py b/cloudinit/cmd/devel/make_mime.py index c7671a93385..ca87428b5ac 100755 --- a/cloudinit/cmd/devel/make_mime.py +++ b/cloudinit/cmd/devel/make_mime.py @@ -1,6 +1,6 @@ # This file is part of cloud-init. See LICENSE file for license information. -"""Generate multi-part mime messages for user-data """ +"""Generate multi-part mime messages for user-data.""" import argparse import sys diff --git a/cloudinit/cmd/main.py b/cloudinit/cmd/main.py index bea1aff68e5..f95f556d6e5 100644 --- a/cloudinit/cmd/main.py +++ b/cloudinit/cmd/main.py @@ -844,6 +844,7 @@ def main(sysv_args=None): "-v", action="version", version="%(prog)s " + (version.version_string()), + help="Show program's version number and exit.", ) parser.add_argument( "--file", @@ -864,8 +865,8 @@ def main(sysv_args=None): "--force", action="store_true", help=( - "force running even if no datasource is" - " found (use at your own risk)" + "Force running even if no datasource is" + " found (use at your own risk)." ), dest="force", default=False, @@ -877,7 +878,7 @@ def main(sysv_args=None): # Each action and its sub-options (if any) parser_init = subparsers.add_parser( - "init", help="Initialize cloud-init and perform initial modules" + "init", help="Initialize cloud-init and perform initial modules." ) parser_init.add_argument( "--local", @@ -906,7 +907,7 @@ def main(sysv_args=None): # This subcommand allows you to run a single module parser_single = subparsers.add_parser( - "single", help="run a single module " + "single", help="Run a single module." ) parser_single.add_argument( "--name", From 20e8c233ae0881c6ebc200fdd6c1decef61043f1 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Fri, 29 Apr 2022 12:41:55 -0600 Subject: [PATCH 5/6] update output in docs --- doc/rtd/topics/cli.rst | 42 ++++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst index 4a26cb45234..2f6ddc85f7f 100644 --- a/doc/rtd/topics/cli.rst +++ b/doc/rtd/topics/cli.rst @@ -9,35 +9,33 @@ option. This can be used against cloud-init itself or any of its subcommands. .. code-block:: shell-session $ cloud-init --help - usage: /usr/bin/cloud-init [-h] [--version] [--file FILES] [--debug] [--force] - {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} - ... - - optional arguments: - -h, --help show this help message and exit - --version, -v show program's version number and exit - --file FILES, -f FILES - additional yaml configuration files to use - --debug, -d show additional pre-action logging (default: False) - --force force running even if no datasource is found (use at - your own risk) + usage: /home/holmanb/cloud-init-main/cloudinit/cmd/main.py [-h] [--version] [--file FILES] [--debug] [--force] + {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status,schema} ... + + options: + -h, --help show this help message and exit + --version, -v Show program's version number and exit. + --file FILES, -f FILES + Use additional yaml configuration files. + --debug, -d Show additional pre-action logging (default: False). + --force Force running even if no datasource is found (use at your own risk). Subcommands: - {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} - init initializes cloud-init and performs initial modules - modules activates modules using a given configuration key - single run a single module - query Query standardized instance metadata from the command - line. + {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status,schema} + init Initialize cloud-init and perform initial modules. + modules Activate modules using a given configuration key. + single Run a single module. + query Query standardized instance metadata from the command line. dhclient-hook Run the dhclient hook to record network info. - features list defined features - analyze Devel tool: Analyze cloud-init logs and data - devel Run development tools - collect-logs Collect and tar all cloud-init debug info + features List defined features. + analyze Devel tool: Analyze cloud-init logs and data. + devel Run development tools. + collect-logs Collect and tar all cloud-init debug info. clean Remove logs and artifacts so cloud-init can re-run. status Report cloud-init status or wait on completion. schema Validate cloud-config files using jsonschema. + The rest of this document will give an overview of each of the subcommands. From 36c8dcdec6109b6c2b16072437524fa2734d3969 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Mon, 2 May 2022 14:55:49 -0600 Subject: [PATCH 6/6] don't invoke from brett's home directory --- doc/rtd/topics/cli.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst index 2f6ddc85f7f..2e209bb44c8 100644 --- a/doc/rtd/topics/cli.rst +++ b/doc/rtd/topics/cli.rst @@ -9,7 +9,7 @@ option. This can be used against cloud-init itself or any of its subcommands. .. code-block:: shell-session $ cloud-init --help - usage: /home/holmanb/cloud-init-main/cloudinit/cmd/main.py [-h] [--version] [--file FILES] [--debug] [--force] + usage: cloud-init [-h] [--version] [--file FILES] [--debug] [--force] {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status,schema} ... options: