docs: adds extensive CLI documentation

The CLI has lacked extensive documentation for most part
and that leaves its users confused about its usage.

This commit attempts to solve that problem by adding some
elaborate docstrings to the commands with examples such
that the users can figure out things by reading it.

riocli/apply/__init__.py

@@ -65,8 +65,46 @@ def apply(
         silent: bool = False,
         show_graph: bool = False,
 ) -> None:
-    """
-    Apply resource manifests
+    """Apply resource manifests.
+
+    The apply command provides the mechanism to create or update
+    resources on rapyuta.io defined in YAML manifests making the
+    process declarative and repeatable. The command can take multiple
+    files, paths or globs as arguments and parse the manifests to
+    create or update resources. It also supports Jinja templating
+    and secret management with sops.
+
+    You can provide a values file with the --values option and a
+    sops encrypted secret file with --secret option. Currently, the
+    command supports only one values and secret file.
+
+    You can use the --show-graph option to visualize the
+    dependency graph of the resources defined in the manifests.
+
+    The --dryrun option can be used to execute the manifests without
+    actually creating the resources. This is useful to validate the
+    manifests before applying them.
+
+    You can specify the number of parallel workers with the --workers
+    option. The default value is 6.
+
+    The --silent, --force or -f option lets you skip the confirmation
+    prompt before applying the manifests. This is particularly useful
+    in CI/CD pipelines.
+
+    Usage Examples:
+
+    Apply a single manifest file with secret and values file.
+
+    $ rio apply -v values.yaml -s secrets.yaml manifest.yaml
+
+    Apply manifests from a directory with secret and values file.
+
+    $ rio apply -v values.yaml -s secrets.yaml templates/
+
+    Apply manifests from a directory without confirmation prompt.
+
+    $ rio apply -f templates/
     """
     glob_files, abs_values, abs_secrets = process_files_values_secrets(
         files, values, secrets)
@@ -133,8 +171,41 @@ def delete(
         workers: int = 6,
         silent: bool = False
 ) -> None:
-    """
-    Removes resources defined in the manifest
+    """Removes resources via manifests
+
+    The delete command provides the mechanism to remove resources on
+    rapyuta.io defined in YAML manifests making the process declarative
+    and repeatable. The command can take multiple files, paths or globs
+    as arguments and parse the manifests to remove resources. It also
+    supports Jinja templating and secret management with sops. You can
+    provide a values file with the --values option and a sops encrypted
+    secret file with --secret option. Currently, the command supports
+    only one values and secret file.
+
+    The --dryrun option can be used to execute the manifests without
+    actually deleting the resources. This is useful to validate the
+    manifests before applying them.
+
+    You can specify the number of parallel workers with the --workers
+    option. The default value is 6.
+
+    The --silent, --force or -f option lets you skip the confirmation
+    prompt before applying the manifests. This is particularly useful
+    in CI/CD pipelines.
+
+    Usage Examples:
+
+        Delete a single manifest file with secret and values file.
+
+        $ rio delete -v values.yaml -s secrets.yaml manifest.yaml
+
+        Delete manifests from a directory with secret and values file.
+
+        $ rio delete -v values.yaml -s secrets.yaml templates/
+
+        Delete manifests from a directory without confirmation prompt.
+
+        $ rio delete -f templates/
     """
     glob_files, abs_values, abs_secrets = process_files_values_secrets(
         files, values, secrets)

riocli/apply/explain.py

@@ -29,6 +29,7 @@
     help='List all examples supported in rio explain command'
 )
 def list_examples() -> None:
+    """List all examples supported in rio explain command."""
     path = Path(__file__).parent.joinpath('manifests')
 
     examples = []
@@ -49,6 +50,24 @@ def list_examples() -> None:
               default=None)
 @click.argument('resource')
 def explain(resource: str, templates: str = None) -> None:
+    """Explain a resource manifest for the given type.
+
+    The explain command can be used to generate a sample
+    resource manifest using the examples that are shown
+    in the output. This is particularly useful to understand
+    the structure of the manifest and the fields that are
+    required for the resource.
+
+    Usage Examples:
+
+        View examples for deployment
+
+        $ rio explain deployment
+
+        View examples for usergroup
+
+        $ rio explain usergroup
+    """
     if templates:
         path = Path(templates)
     else:

riocli/apply/template.py

@@ -36,8 +36,22 @@
                    'expects sops to be authorized for decoding files on this computer')
 @click.argument('files', nargs=-1)
 def template(values: str, secrets: str, files: Iterable[str]) -> None:
-    """
-    Print manifests with filled values
+    """Print manifests with values and secrets applied
+
+    The template command can be used to preview the manifests
+    with values and secrets applied. This is particularly useful
+    to check if the values and secrets are correctly substituted
+    in the manifests before applying them.
+
+    Just like the apply command, the template command also accepts
+    a list of files as arguments. You can specify one or more files,
+    directories or glob pattern.
+
+    However, it will only accept on values and secrets file as input.
+
+    Usage Examples:
+
+    rio template manifests/*.yaml -v values.yaml -s secrets.yaml
     """
     glob_files, abs_values, abs_secrets = process_files_values_secrets(
         files, values, secrets)

riocli/auth/__init__.py

@@ -32,9 +32,7 @@
     help_options_color=Colors.GREEN,
 )
 def auth():
-    """
-    Account and Login on Rapyuta.io
-    """
+    """Login and token management"""
     pass
 
 

riocli/auth/login.py

@@ -56,12 +56,51 @@ def login(
         interactive: bool,
         auth_token: str,
 ) -> None:
-    """
-    Log into your rapyuta.io account using the CLI. This is required to
-    use most commands of the CLI.
+    """Log into your rapyuta.io account.
+
+    This is the first step to start using the CLI.
     
-    You can log in with your email and password or just with and auth token
-    if you already have one.
+    You can log in with your email and password or
+    just with and auth token if you already have one.
+    The command works in an interactive mode by default
+    and will prompt you to enter your credentials and
+    select the organization and project you want to work
+    with.
+
+    You can also use the command in non-interactive mode
+    by providing the email and password as arguments and
+    setting the --no-interactive or --silent flag. In this
+    mode, you can also set the organization and project
+    using the --organization and --project flags. If you
+    do not provide the organization and project, you will
+    have to set them later using the `rio organization select`
+    and `rio project select` commands.
+
+    Note: If you have special characters in your password, then
+    consider putting them in quotes to avoid the terminal from
+    interpreting them otherwise.
+
+    Usage Examples:
+
+        Login interactively
+
+        $ rio auth login
+
+        Login interactively with email and password
+
+        $ rio auth login --email YOUR_EMAIL --password YOUR_PASSWORD
+
+        Login non-interactively with email and password
+
+        $ rio auth login --email YOUR_EMAIL --password YOUR_PASSWORD --no-interactive
+
+        Login non-interactively with email, password, organization and project
+
+        $ rio auth login --email YOUR_EMAIL --password YOUR_PASSWORD --organization YOUR_ORG --project YOUR_PROJECT --silent
+
+        Login with auth token
+
+        $ rio auth login --auth-token YOUR_AUTH_TOKEN
     """
     ctx = get_root_context(ctx)
 

riocli/auth/logout.py

@@ -25,9 +25,7 @@
 )
 @click.pass_context
 def logout(ctx: click.Context):
-    """
-    Log out from the Rapyuta.io account using the CLI.
-    """
+    """Log out from your rapyuta.io account."""
     if not ctx.obj.exists:
         return
 

riocli/auth/refresh_token.py

@@ -18,7 +18,7 @@
 from riocli.constants import Colors, Symbols
 from riocli.exceptions import LoggedOut
 
-
+# TODO(pallab): Consider removing this since we don't save passwords anymore.
 @click.command(
     'refresh-token',
     cls=HelpColorsCommand,
@@ -34,9 +34,7 @@
     help='Password for the rapyuta.io account',
 )
 def refresh_token(ctx: click.Context, password: str):
-    """
-    Refreshes the authentication token after it expires
-    """
+    """Refreshes the authentication token after it expires"""
     email = ctx.obj.data.get('email_id', None)
 
     try:

riocli/auth/status.py

@@ -25,9 +25,7 @@
 )
 @click.pass_context
 def status(ctx: click.Context):
-    """
-    Shows the login status of the CLI
-    """
+    """Shows the current login status."""
     if not ctx.obj.exists:
         click.secho('🔒You are logged out', fg=Colors.YELLOW)
         raise SystemExit(1)

riocli/auth/token.py

@@ -32,8 +32,17 @@
 @click.option("--level", default=0,
               help="Level of the token. 0 = low, 1 = med, 2 = high")
 def token(email: str, password: str, level: int = 0):
-    """
-    Generates a fresh rapyuta.io auth token
+    """Generates a new rapyuta.io auth token.
+
+    There may be times when you just need a new auth token.
+    This command will generate a new token for you based on
+    the level you specify. The default level is 0. You will
+    have to specify a valid email and password.
+
+    The token levels are as follows:
+    0 = low, 24 hours
+    1 = medium, 7 days
+    2 = high, 30 days
     """
     config = Configuration()
 

riocli/bootstrap.py

@@ -65,6 +65,7 @@
 )
 @click.pass_context
 def cli(ctx: Context, config: str = None):
+    """Manage rapyuta.io features on the command-line"""
     ctx.obj = Configuration(filepath=config)
 
 

riocli/chart/apply.py

@@ -56,7 +56,34 @@ def apply_chart(
         retry_count: int = 50,
         retry_interval: int = 6,
         silent: bool = False) -> None:
-    """Install a chart from the rapyuta-charts repository."""
+    """Install a chart from the rapyuta-charts repository.
+
+    This command is based on the `rio apply` command. However,
+    the manifests are pulled from rapyuta-charts repository on
+    GitHub. A rapyuta chart is collection of manifest files with
+    default values.
+
+    The chart can be customized by providing custom values and
+    secrets files using the --values and --secrets flags respectively.
+
+    The --workers flag can be used to specify the number of parallel
+    workers while running the apply command. The default value is 6.
+
+    The --dryrun flag can be used to test the installation process
+    without actually installing the chart.
+
+    Repository: https://github.com/rapyuta-robotics/rapyuta-charts
+
+    Usage Examples:
+
+     Apply a chart with values and secrets files
+
+     $ rio chart apply ioconfig-syncer -v values.yaml -s secrets.yaml
+
+     Apply a chart with values and secrets files without confirmation
+
+     $ rio chart apply ioconfig-syncer -v values.yaml -s secrets.yaml -f
+    """
     versions = find_chart(chart)
     if len(versions) > 1:
         click.secho(

riocli/chart/delete.py

@@ -44,7 +44,33 @@ def delete_chart(
         secrets: str,
         dryrun: bool = False,
         silent: bool = False) -> None:
-    """Uninstall a chart."""
+    """Delete a chart.
+
+    The delete command is based on the `rio delete` command
+    and is used to delete a chart that you have installed
+    using the `rio chart apply` command. The manifest files
+    are pulled from the rapyuta-charts repository. The command
+    accepts custom values and secrets files that you may have
+    used while installing the chart.
+
+    You can skip confirmation by using the `--silent` or `--force`
+    or the `-f` flag.
+
+    The `--dryrun` flag can be used to test the deletion process
+    without actually deleting the chart.
+
+    Repository: https://github.com/rapyuta-robotics/rapyuta-charts
+
+    Usage Examples:
+
+        Delete a chart
+
+        $ rio chart delete postgres
+
+        Delete a chart without confirmation
+
+        $ rio chart delete postgres --silent
+    """
     versions = find_chart(chart)
     if len(versions) > 1:
         click.secho('More than one charts are available, '