docs: update maas-anvil documentation

anvil-python/anvil/commands/inspect.py

@@ -38,14 +38,20 @@
 snap = Snap()
 
 
-@click.group(invoke_without_command=True)
+@click.group(
+    invoke_without_command=True,
+    epilog="""
+    \b
+    Inspect the MAAS Anvil cluster.
+    maas-anvil inspect
+    """,
+)
 @click.pass_context
 def inspect(ctx: click.Context) -> None:
-    """Inspect the maas-anvil installation.
-
-    This script will inspect your installation. It will report any issue
-    it finds, and create a tarball of logs and traces which can be
-    attached to an issue filed against the maas-anvil project.
+    """Inspects the cluster and reports any issues it finds. A tarball of
+    logs and traces is created.
+    You can attach this tarball to an issue filed in the MAAS Anvil Github
+    repository. github.com/canonical/maas-anvil
     """
     preflight_checks = []
     preflight_checks.append(DaemonGroupCheck())

anvil-python/anvil/commands/manifest.py

@@ -31,6 +31,7 @@
 
 from anvil.jobs.checks import DaemonGroupCheck, VerifyBootstrappedCheck
 from anvil.jobs.manifest import Manifest
+from anvil.utils import FormatEpilogCommand
 
 LOG = logging.getLogger(__name__)
 console = Console()
@@ -70,17 +71,24 @@ def generate_software_manifest(manifest: Manifest) -> str:
         raise click.ClickException(f"Manifest generation failed: {e!s}")
 
 
-@click.command()
+@click.command(
+    cls=FormatEpilogCommand,
+    epilog="""
+    \b
+    List previously used manifest files.
+    maas-anvil manifest list
+    """,
+)
 @click.option(
     "-f",
     "--format",
     type=click.Choice([FORMAT_TABLE, FORMAT_YAML]),
     default=FORMAT_TABLE,
-    help="Output format.",
+    help="Output format of the list.",
 )
 @click.pass_context
 def list(ctx: click.Context, format: str) -> None:
-    """List manifests"""
+    """Lists manifest files that were used in the cluster."""
     deployment: Deployment = ctx.obj
     client = deployment.get_client()
     manifests = []
@@ -109,13 +117,22 @@ def list(ctx: click.Context, format: str) -> None:
         click.echo(yaml.dump(manifests))
 
 
-@click.command()
-@click.option("--id", type=str, prompt=True, help="Manifest ID")
+@click.command(
+    cls=FormatEpilogCommand,
+    epilog="""
+    \b
+    Show the contents of the most recently committed manifest file.
+    maas-anvil manifest show --id=latest
+    """,
+)
+@click.option(
+    "--id", type=str, prompt=True, help="The database id of the manifest file."
+)
 @click.pass_context
 def show(ctx: click.Context, id: str) -> None:
-    """Show Manifest data.
-
-    Use '--id=latest' to get the last committed manifest.
+    """Shows the contents of a manifest file given an id.
+    Get ids using the 'manifest list' command. Use '--id=latest' to show the most
+    recently committed manifest.
     """
     deployment: Deployment = ctx.obj
     client = deployment.get_client()
@@ -132,7 +149,15 @@ def show(ctx: click.Context, id: str) -> None:
         click.echo(f"Error: No manifest exists with id {id}")
 
 
-@click.command()
+@click.command(
+    cls=FormatEpilogCommand,
+    epilog="""
+    \b
+    Generate a manifest file with (default) configuration to be saved in the default
+    location of '$HOME/.config/anvil/manifest.yaml'
+    maas-anvil manifest generate
+    """,
+)
 @click.option(
     "-o",
     "--output",
@@ -144,11 +169,8 @@ def generate(
     ctx: click.Context,
     output: Path | None = None,
 ) -> None:
-    """Generate manifest file.
-
-    Generate manifest file with the deployed configuration.
-    If the cluster is not bootstrapped, fallback to default
-    configuration.
+    """Generates a manifest file. Either with the configuration of the currently deployed
+    MAAS Anvil cluster or, if no cluster was bootstrapped yet, a default configuration.
     """
     deployment: Deployment = ctx.obj
 

anvil-python/anvil/commands/prepare_node.py

@@ -16,6 +16,8 @@
 import click
 from rich.console import Console
 
+from anvil.utils import FormatEpilogCommand
+
 console = Console()
 
 
@@ -82,7 +84,16 @@
 """
 
 
-@click.command()
+@click.command(
+    cls=FormatEpilogCommand,
+    epilog="""
+    \b
+    Prepare a node for usage with MAAS Anvil by generating the 'prepare-node-script' and
+    running it immediately by piping it to bash.
+    maas-anvil prepare-node-script | bash -x
+    """,
+)
 def prepare_node_script() -> None:
-    """Generate script to prepare a node for Anvil use."""
+    """Generates a script to prepare the node for use with MAAS Anvil.
+    This must be run on every node on which you want to use MAAS Anvil."""
     console.print(PREPARE_NODE_TEMPLATE, soft_wrap=True)

anvil-python/anvil/commands/refresh.py

@@ -28,17 +28,28 @@
 from anvil.commands.upgrades.intra_channel import LatestInChannelCoordinator
 from anvil.jobs.manifest import AddManifestStep, Manifest
 from anvil.provider.local.deployment import LocalDeployment
+from anvil.utils import FormatEpilogCommand
 
 LOG = logging.getLogger(__name__)
 console = Console()
 
 
-@click.command()
+@click.command(
+    cls=FormatEpilogCommand,
+    epilog="""
+    \b
+    Refresh the MAAS Anvil cluster.
+    maas-anvil refresh
+    """,
+)
 @click.option(
     "-m",
     "--manifest",
     "manifest_path",
-    help="Manifest file.",
+    help=(
+        "If provided, the cluster is refreshed with the configuration "
+        "specified in the manifest file."
+    ),
     type=click.Path(
         exists=True, dir_okay=False, path_type=Path, allow_dash=True
     ),
@@ -49,17 +60,20 @@
     is_flag=True,
     show_default=True,
     default=False,
-    help="Upgrade MAAS Anvil release.",
+    help=(
+        "Allows charm upgrades if the new manifest specifies charms in channels "
+        "with higher tracks than the current one."
+    ),
 )
 @click.pass_context
 def refresh(
     ctx: click.Context,
     manifest_path: Path | None = None,
     upgrade_release: bool = False,
 ) -> None:
-    """Refresh deployment.
-
-    Refresh the deployment and allow passing new configuration options.
+    """Updates all charms within their current channel.
+    A manifest file can be passed to refresh the deployment with
+    new configuration.
     """
 
     deployment: LocalDeployment = ctx.obj

anvil-python/anvil/commands/utils.py

@@ -22,15 +22,26 @@
 
 from anvil.jobs.checks import VerifyBootstrappedCheck
 from anvil.provider.local.deployment import LocalDeployment
+from anvil.utils import FormatEpilogCommand
 
 LOG = logging.getLogger(__name__)
 console = Console()
 
 
-@click.command()
+@click.command(
+    cls=FormatEpilogCommand,
+    epilog="""
+    \b
+    Log into the Juju controller to manually interact with the Juju controller created
+    by MAAS Anvil.
+    maas-anvil juju-login
+    """,
+)
 @click.pass_context
 def juju_login(ctx: click.Context) -> None:
-    """Login to the controller with current host user."""
+    """Logs into the Juju controller used by MAAS Anvil.
+    The login is performed using the current host user.
+    """
     deployment: LocalDeployment = ctx.obj
     run_preflight_checks(
         [VerifyBootstrappedCheck(deployment.get_client())], console

anvil-python/anvil/main.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 import click
 from snaphelpers import Snap
 from sunbeam import log
@@ -29,30 +30,45 @@
 from anvil.commands.utils import juju_login
 from anvil.provider.local.commands import LocalProvider
 from anvil.provider.local.deployment import LocalDeployment
-from anvil.utils import CatchGroup
+from anvil.utils import CatchGroup, FormatCommandGroupsGroup
 
 # Update the help options to allow -h in addition to --help for
 # triggering the help for various commands
 CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
 
 
-@click.group("init", context_settings=CONTEXT_SETTINGS, cls=CatchGroup)
+@click.group(
+    "init", context_settings=CONTEXT_SETTINGS, cls=FormatCommandGroupsGroup
+)
 @click.option("--quiet", "-q", default=False, is_flag=True)
 @click.option("--verbose", "-v", default=False, is_flag=True)
 @click.pass_context
 def cli(ctx: click.Context, quiet: bool, verbose: bool) -> CatchGroup:  # type: ignore[empty-body]
-    """Anvil is a MAAS installer for MAAS charms.
+    """MAAS Anvil is an installer that makes deploying MAAS charms in HA easy.
 
-    To get started with a single node, all-in-one MAAS installation, start
-    with initializing the local node. Once the local node has been initialized,
-    run the bootstrap process to get a live MAAS deployment.
+    To get started run the prepare-node-script command and bootstrap the first
+    node. For more details read the docs at: github.com/canonical/maas-anvil
     """
 
 
-@click.group("manifest", context_settings=CONTEXT_SETTINGS, cls=CatchGroup)
+@click.group(
+    "manifest",
+    context_settings=CONTEXT_SETTINGS,
+    cls=CatchGroup,
+    epilog="""
+    \b
+    Generate a manifest file with (default) configuration to be saved in the default
+    location of '$HOME/.config/anvil/manifest.yaml'
+    maas-anvil manifest generate
+    """,
+)
 @click.pass_context
 def manifest(ctx: click.Context) -> None:
-    """Manage manifests (read-only commands)"""
+    """Generates and manages manifest files.
+    A manifest file is a declarative YAML file with which configurations for
+    a MAAS Anvil cluster deployment can be set. The manifest commands are read
+    only. A manifest can be applied with "cluster bootstrap" or "cluster refresh".
+    """
 
 
 def main() -> None: