Update docs

canonical · Aug 8, 2024 · 577fa19 · 577fa19
1 parent 0787d62
commit 577fa19
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 39 deletions.
diff --git a/cloudinit/cmd/main.py b/cloudinit/cmd/main.py
@@ -979,7 +979,10 @@ 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=(
+            "DEPRECATED: Initialize cloud-init and perform initial modules."
+        ),
     )
     parser_init.add_argument(
         "--local",
@@ -1002,7 +1005,8 @@ def main(sysv_args=None):
 
     # These settings are used for the 'config' and 'final' stages
     parser_mod = subparsers.add_parser(
-        "modules", help="Activate modules using a given configuration key."
+        "modules",
+        help=("DEPRECATED: Activate modules using a given configuration key."),
     )
     extra_help = lifecycle.deprecate(
         deprecated="`init`",
@@ -1033,7 +1037,10 @@ 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=(
+            "Manually run a single module. Useful for testing during development."
+        ),
     )
     parser_single.add_argument(
         "--name",

diff --git a/doc/man/cloud-init.1 b/doc/man/cloud-init.1
@@ -12,27 +12,19 @@ This is done by identifying the cloud platform that is in use, reading
 provided cloud metadata and optional vendor and user
 data, and then initializing the instance as requested.
 
-Generally, this command is not normally meant to be run directly by
-the user. However, some subcommands may useful for development or
-debug of deployments.
-
 .SH OPTIONS
 .TP
 .B "-h, --help"
 Show help message and exit.
 
-.TP
-.B "-d, --debug"
-Show additional pre-action logging (default: False).
-
-.TP
-.B "--force"
-Force running even if no datasource is found (use at your own risk).
-
 .TP
 .B "-v, --version"
 Show program's version number and exit.
 
+.TP
+.B "--all-stages"
+INTERNAL: Run cloud-init's stages under a single process using a syncronization protocol. This is not intended for CLI usage.
+
 .SH SUBCOMMANDS
 Please see the help output for each subcommand for additional details,
 flags, and subcommands.
@@ -57,14 +49,6 @@ Run development tools. See help output for subcommand details.
 .B "features"
 List defined features.
 
-.TP
-.B "init"
-Initialize cloud-init and execute initial modules.
-
-.TP
-.B "modules"
-Activate modules using a given configuration key.
-
 .TP
 .B "query"
 Query standardized instance metadata from the command line.
@@ -75,12 +59,30 @@ Validate cloud-config files using jsonschema.
 
 .TP
 .B "single"
-Run a single module.
+Manually run a single module. Useful for testing during development.
 
 .TP
 .B "status"
 Report cloud-init status or wait on completion.
 
+.SH DEPRECATED
+
+.TP
+.B "-d, --debug"
+Show additional pre-action logging (default: False).
+
+.TP
+.B "--force"
+Force running even if no datasource is found (use at your own risk).
+
+.TP
+.B "init"
+Initialize cloud-init and execute initial modules.
+
+.TP
+.B "modules"
+Activate modules using a given configuration key.
+
 .SH EXIT STATUS
 
 .IP
@@ -95,4 +97,4 @@ Report cloud-init status or wait on completion.
 Copyright (C) 2020 Canonical Ltd. License GPL-3 or Apache-2.0
 
 .SH SEE ALSO
-Full documentation at: <https://cloudinit.readthedocs.io>
+Full documentation at: <https://docs.cloud-init.io>
diff --git a/doc/rtd/explanation/boot.rst b/doc/rtd/explanation/boot.rst
@@ -48,8 +48,7 @@ Detect
 A platform identification tool called ``ds-identify`` runs in the first stage.
 This tool detects which platform the instance is running on. This tool is
 integrated into the init system to disable cloud-init when no platform is
-found, and enable cloud-init when a valid platform is detected. This stage
-might not be present for every installation of cloud-init.
+found, and enable cloud-init when a valid platform is detected.
 
 .. _boot-Local:
 
@@ -89,9 +88,8 @@ including persistent device naming with old MAC addresses.
 
 This stage must block network bring-up or any stale configuration that might
 have already been applied. Otherwise, that could have negative effects such
-as DHCP hooks or broadcast of an old hostname. It would also put the system
-in an odd state to recover from, as it may then have to restart network
-devices.
+broadcast of an old hostname. It would also put the system in an odd state to
+recover from, as it may then have to restart network devices.
 
 ``Cloud-init`` then exits and expects for the continued boot of the operating
 system to bring network configuration up as configured.

diff --git a/doc/rtd/reference/cli.rst b/doc/rtd/reference/cli.rst
@@ -15,20 +15,20 @@ Example output:
 
 .. code-block::
 
-   usage: cloud-init [-h] [--version] [--debug] [--force]
-                                                               {init,modules,single,query,features,analyze,devel,collect-logs,clean,status,schema} ...
+   usage: cloud-init [-h] [--version] [--debug] [--force] [--all-stages] {init,modules,single,query,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.
       --debug, -d           Show additional pre-action logging (default: False).
       --force               Force running even if no datasource is found (use at your own risk).
+      --all-stages          Run cloud-init's stages under a single process using a syncronization protocol. This is not intended for CLI usage.
 
     Subcommands:
       {init,modules,single,query,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.
+        init                DEPRECATED: Initialize cloud-init and perform initial modules.
+        modules             DEPRECATED: Activate modules using a given configuration key.
+        single              Manually run a single module. Useful for testing during development.
         query               Query standardized instance metadata from the command line.
         features            List defined features.
         analyze             Devel tool: Analyze cloud-init logs and data.
@@ -185,8 +185,8 @@ Example output:
 
 .. _cli_init:
 
-:command:`init`
-===============
+:command:`init` (deprecated)
+============================
 
 Generally run by OS init systems to execute ``cloud-init``'s stages:
 *init* and *init-local*. See :ref:`boot_stages` for more info.
@@ -200,8 +200,8 @@ generally gated to run only once due to semaphores in
 
 .. _cli_modules:
 
-:command:`modules`
-==================
+:command:`modules` (deprecated)
+===============================
 
 Generally run by OS init systems to execute ``modules:config`` and
 ``modules:final`` boot stages. This executes cloud config :ref:`modules`