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.

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contribution Guidelines
+## Setup your development environment
+
+The project uses [pipenv](https://pipenv.pypa.io/en/latest/) for
+development. It needs to be installed to setup the development environment.
+
+``` bash
+pip install pipenv
+```
+
+Once Pipenv is installed, a Python virtual environment can be quickly
+bootstrapped by running the following commands in the root of the repository.
+
+``` bash
+pipenv install --dev
+```
+
+This will create a virtual environment in the Pipenv's preconfigured location
+(if one doesn't already exists). It will also install all the dependencies and
+`riocli` package in the location.
+
+To run the CLI (or any command) under the context of Pipenv's virtual
+environment, prepend the commands with `pipenv run`
+
+```bash
+pipenv run rio
+```
+
+To run the RIO CLI from the source directly, you can use `riocli` module
+directly.
+
+``` bash
+pipenv run python -m riocli
+```
+
+New dependencies can be installed directly using `pipenv`. This modifies the
+`Pipfile` and `Pipfile.lock`.
+
+``` bash
+pipenv install {dependency}
+```
+
+But using the `pipenv` directly doesn't sync the dependencies in the
+`setup.py` file. For this, the project uses a utility called `pipenv-setup`
+which allows us to sync the dependencies.
+
+``` bash
+pipenv run pipenv-setup sync
+```

README.md

@@ -1,9 +1,8 @@
-# Rapyuta CLI
+# rapyuta.io CLI
 
-Rapyuta CLI exposes features of Rapyuta.io platform on the command-line.
+The rapyuta.io CLI exposes features of the rapyuta.io cloud platform on the command-line.
 
-The application is written in Python 3 and it is distributed through PyPI for
-Python 3 environments.
+The application is written in Python 3, and it is distributed through PyPI for Python 3 environments.
 
 For Reference on directory structure please refer Please have a look at the
 corresponding article:
@@ -18,7 +17,6 @@ following command.
 pip install rapyuta-io-cli
 ```
 
-
 On Unix-like systems it places the `rio` executable in the user's PATH. On
 Windows it places the `rio.exe` in the centralized `Scripts` directory
 which should be in the user's PATH.
@@ -39,57 +37,9 @@ To begin using the CLI, it must be authenticated with the Platform.
 rio auth login
 ```
 
-The Email and Password can either be given through flags (for scripting
-purposes) or interactively through the Prompts.
-
-NOTE: Entering password as a Flag is not recommended because it leaves the
-Traces.
-
-## Development
-
-Rio CLI project uses [Pipenv](https://pipenv.pypa.io/en/latest/) for
-development. It needs to be installed to setup the development environment.
-
-``` bash
-pip install pipenv
-```
-
-Once Pipenv is installed, a Python virtual environment can be quickly
-bootstrapped by running the following commands in the root of the repository.
-
-``` bash
-pipenv install --dev
-```
-
-This will create a virtual environment in the Pipenv's preconfigured location
-(if one doesn't already exists). It will also install all the dependencies and
-`riocli` package in the location.
+The `email` and `password` can either be given through flags (for scripting purposes) or interactively through the prompt.
 
-To run the CLI (or any command) under the context of Pipenv's virtual
-environment, prepend the commands with `pipenv run`
-
-```bash
-pipenv run rio
-```
-
-To run the RIO CLI from the source directly, you can use `riocli` module
-directly.
-
-``` bash
-pipenv run python -m riocli
-```
-
-New dependencies can be installed directly using `pipenv`. This modifies the
-`Pipfile` and `Pipfile.lock`.
+NOTE: Entering the password as a flag is not recommended because it leaves the traces.
 
-``` bash
-pipenv install {dependency}
-```
-
-But using the `pipenv` directly doesn't sync the dependencies in the
-`setup.py` file. For this, the project uses a utility called `pipenv-setup`
-which allows us to sync the dependencies.
-
-``` bash
-pipenv run pipenv-setup sync
-```
+## References
+* [Development Guide](CONTRIBUTING.md)

docs/source/conf.py

@@ -2,7 +2,7 @@
 import os
 import sys
 
-project = u'rapyuta.io CLI'
+project = u'CLI'
 copyright = u'2024, Rapyuta Robotics'
 author = u'Rapyuta Robotics'
 
@@ -26,8 +26,8 @@
 html_favicon = 'favicon.ico'
 html_static_path = ['_static']
 html_theme_options = {
-    "light_logo": "logo-light-mode.png",
-    "dark_logo": "logo-dark-mode.png",
+    "light_logo": "logo-light-mode.svg",
+    "dark_logo": "logo-dark-mode.svg",
 }
 html_css_files = ['css/rio-sphinx.css']
 html_js_files = ['js/rio-sphinx.js']

docs/source/index.rst

@@ -1,7 +1,7 @@
-Welcome to Rapyuta.io CLI documentation!
+Welcome to rapyuta.io CLI documentation!
 ========================================
 
-Rapyuta CLI exposes features of Rapyuta.io platform on the command-line.
+The rapyuta.io CLI (aka riocli) exposes features of Rapyuta.io platform on the command-line.
 
 The application is written in Python 3 and it is distributed through PyPI for
 Python 3 environments.

riocli/apply/__init__.py

@@ -32,19 +32,19 @@
     help_options_color=Colors.GREEN,
 )
 @click.option('--dryrun', '-d', is_flag=True, default=False,
-              help='dry run the yaml files without applying any change')
+              help='Dry run the yaml files without applying any change')
 @click.option('--show-graph', '-g', is_flag=True, default=False,
               help='Opens a mermaid.live dependency graph')
 @click.option('--values', '-v',
-              help="path to values yaml file. key/values "
+              help="Path to values yaml file. Key/values "
                    "specified in the values file can be "
                    "used as variables in template YAMLs")
 @click.option('--secrets', '-s',
-              help="secret files are sops encoded value files. "
+              help="Secret files are sops encoded value files. "
                    "rio-cli expects sops to be authorized for "
                    "decoding files on this computer")
 @click.option('--workers', '-w',
-              help="number of parallel workers while running apply "
+              help="Number of parallel workers while running apply "
                    "command. defaults to 6.", type=int)
 @click.option('-f', '--force', '--silent', 'silent', is_flag=True,
               type=click.BOOL, default=False,
@@ -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)
@@ -105,7 +143,7 @@ def apply(
     help_options_color=Colors.GREEN,
 )
 @click.option('--dryrun', '-d', is_flag=True, default=False,
-              help='dry run the yaml files without applying any change')
+              help='Dry run the yaml files without applying any change')
 @click.option('--values', '-v',
               help="Path to values yaml file. key/values specified in the"
                    " values file can be used as variables in template YAMLs")
@@ -116,7 +154,7 @@ def apply(
               type=click.BOOL, default=False,
               help="Skip confirmation")
 @click.option('--workers', '-w',
-              help="number of parallel workers while running apply "
+              help="Number of parallel workers while running apply "
                    "command. defaults to 6.", type=int)
 @click.option('--retry-count', '-rc', type=int, default=50,
               help="Number of retries before a resource creation times out status, defaults to 50")
@@ -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)