Merge pull request #78 from tdviet/devel

Improving help texts

docs/intro.rst

@@ -24,7 +24,7 @@ The most notable features of FedCloud client are following:
 
 * can perform an action/command on all OpenStack sites in EGI infrastructure by specifying `--site ALL_SITES`.
 
-* can be used in `scripts <https://fedcloudclient.fedcloud.eu/scripts.html>`_ for automation or called directly
+* can be used in `scripts for automation<https://fedcloudclient.fedcloud.eu/scripts.html>`_ or called directly
   from `Python codes <https://fedcloudclient.fedcloud.eu/development.html>`_.
 
 Five modules are included: **fedcloudclient.checkin** for operation with EGI Check-in like getting tokens, **

docs/usage.rst

@@ -286,8 +286,8 @@ VOs and so on.
     # export OS_ACCESS_TOKEN=`oidc-token egi`
 
 The main differences between *"fedcloud endpoint env"* and *"fedcloud site env"* commands are that the second command
-needs VO name as input parameter instead of project ID; and it does not need access token (and therefore it does not
-set OS_ACCESS_TOKEN).
+needs VO name as input parameter instead of project ID. The command may set also environment variable OS_ACCESS_TOKEN,
+if access token is provided, otherwise it will print notification.
 
 
 fedcloud openstack commands

fedcloudclient/decorators.py

@@ -20,6 +20,7 @@ def oidc_access_token_params(func):
         "--oidc-access-token",
         help="OIDC access token",
         envvar="OIDC_ACCESS_TOKEN",
+        metavar="token",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -33,6 +34,7 @@ def oidc_refresh_token_params(func):
         "--oidc-refresh-token",
         help="OIDC refresh token",
         envvar="OIDC_REFRESH_TOKEN",
+        metavar="token",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -47,6 +49,7 @@ def site_params(func):
         help="Name of the site",
         required=True,
         envvar="EGI_SITE",
+        metavar="site-name",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -59,17 +62,18 @@ def all_site_params(func):
     @optgroup.group(
         "Site",
         cls=RequiredMutuallyExclusiveOptionGroup,
-        help="Specify one Openstack site or all sites",
+        help="Single Openstack site or all sites",
     )
     @optgroup.option(
         "--site",
         help="Name of the site or ALL_SITES",
         envvar="EGI_SITE",
+        metavar="site-name",
     )
     @optgroup.option(
         "--all-sites",
         "-a",
-        help="All sites (equivalent --site ALL_SITES)",
+        help="Short option for all sites (equivalent --site ALL_SITES)",
         is_flag=True,
     )
     @functools.wraps(func)
@@ -85,6 +89,7 @@ def project_id_params(func):
         help="Project ID",
         required=True,
         envvar="OS_PROJECT_ID",
+        metavar="project-id",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -99,6 +104,7 @@ def auth_file_params(func):
         help="Authorization file",
         default="auth.dat",
         show_default=True,
+        metavar="auth-file",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -113,6 +119,7 @@ def vo_params(func):
         help="Name of the VO",
         required=True,
         envvar="EGI_VO",
+        metavar="vo-name",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -146,38 +153,44 @@ def oidc_params(func):
     :return:
     """
 
-    @optgroup.group("OIDC token", help="Provide at least one type of tokens")
+    @optgroup.group("OIDC token", help="oidc-gent account or tokens for authentication")
     @optgroup.option(
-        "--oidc-client-id",
-        help="OIDC client id",
-        envvar="OIDC_CLIENT_ID",
+        "--oidc-agent-account",
+        help="Account name in oidc-agent",
+        envvar="OIDC_AGENT_ACCOUNT",
+        metavar="account",
     )
     @optgroup.option(
-        "--oidc-client-secret",
-        help="OIDC client secret",
-        envvar="OIDC_CLIENT_SECRET",
+        "--oidc-access-token",
+        help="OIDC access token",
+        envvar="OIDC_ACCESS_TOKEN",
+        metavar="token",
     )
     @optgroup.option(
         "--oidc-refresh-token",
         help="OIDC refresh token",
         envvar="OIDC_REFRESH_TOKEN",
+        metavar="token",
     )
     @optgroup.option(
-        "--oidc-access-token",
-        help="OIDC access token",
-        envvar="OIDC_ACCESS_TOKEN",
+        "--oidc-client-id",
+        help="OIDC client id",
+        envvar="OIDC_CLIENT_ID",
+        metavar="id",
+    )
+    @optgroup.option(
+        "--oidc-client-secret",
+        help="OIDC client secret",
+        envvar="OIDC_CLIENT_SECRET",
+        metavar="secret",
     )
     @optgroup.option(
         "--oidc-url",
-        help="OIDC URL",
+        help="OIDC identity provider URL",
         envvar="OIDC_URL",
         default=DEFAULT_OIDC_URL,
         show_default=True,
-    )
-    @optgroup.option(
-        "--oidc-agent-account",
-        help="Account name in oidc-agent",
-        envvar="OIDC_AGENT_ACCOUNT",
+        metavar="provider-url",
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -204,20 +217,47 @@ def openstack_params(func):
         envvar="OPENSTACK_AUTH_PROTOCOL",
         default=DEFAULT_PROTOCOL,
         show_default=True,
+        metavar="",
+    )
+    @optgroup.option(
+        "--openstack-auth-provider",
+        help="Identity provider",
+        envvar="OPENSTACK_AUTH_PROVIDER",
+        default=DEFAULT_IDENTITY_PROVIDER,
+        show_default=True,
+        metavar="",
     )
     @optgroup.option(
         "--openstack-auth-type",
         help="Authentication type",
         envvar="OPENSTACK_AUTH_TYPE",
         default=DEFAULT_AUTH_TYPE,
         show_default=True,
+        metavar="",
+    )
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def output_format_params(func):
+    @optgroup.group(
+        "Output format",
+        help="Parameters for formatting outputs",
     )
     @optgroup.option(
-        "--openstack-auth-provider",
-        help="Identity provider",
-        envvar="OPENSTACK_AUTH_PROVIDER",
-        default=DEFAULT_IDENTITY_PROVIDER,
-        show_default=True,
+        "--ignore-missing-vo",
+        "-i",
+        help="Ignore sites that do not support the VO",
+        is_flag=True,
+    )
+    @optgroup.option(
+        "--json-output",
+        "-j",
+        help="Print output as JSON object",
+        is_flag=True,
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):

fedcloudclient/ec3.py

@@ -138,8 +138,8 @@ def refresh(
 
 
 @ec3.command()
-@oidc_params
 @site_vo_params
+@oidc_params
 @auth_file_params
 @click.option(
     "--template-dir",

fedcloudclient/endpoint.py

@@ -218,8 +218,8 @@ def endpoint():
 
 
 @endpoint.command()
-@oidc_params
 @all_site_params
+@oidc_params
 def projects(
     oidc_client_id,
     oidc_client_secret,
@@ -255,9 +255,9 @@ def projects(
 
 
 @endpoint.command()
-@oidc_params
 @site_params
 @project_id_params
+@oidc_params
 def token(
     oidc_client_id,
     oidc_client_secret,
@@ -296,6 +296,7 @@ def token(
 
 
 @endpoint.command()
+@all_site_params
 @click.option(
     "--service-type",
     default="org.openstack.nova",
@@ -314,7 +315,6 @@ def token(
     help="Monitoring status",
     show_default=True,
 )
-@all_site_params
 def list(service_type, production, monitored, site, all_sites):
     """
     List endpoints in site(s), will query GOCDB
@@ -327,9 +327,9 @@ def list(service_type, production, monitored, site, all_sites):
 
 
 @endpoint.command()
-@oidc_params
 @site_params
 @project_id_params
+@oidc_params
 def env(
     oidc_client_id,
     oidc_client_secret,

fedcloudclient/openstack.py

@@ -20,6 +20,7 @@
     DEFAULT_PROTOCOL,
     all_site_params,
     openstack_params,
+    output_format_params,
     site_params,
     vo_params,
 )
@@ -221,22 +222,11 @@ def print_result(
 
 
 @click.command(context_settings={"ignore_unknown_options": True})
-@oidc_params
-@openstack_params
 @all_site_params
 @vo_params
-@click.option(
-    "--ignore-missing-vo",
-    "-i",
-    help="Ignore sites that do not support the VO",
-    is_flag=True,
-)
-@click.option(
-    "--json-output",
-    "-j",
-    help="Print output as JSON object",
-    is_flag=True,
-)
+@oidc_params
+@output_format_params
+@openstack_params
 @click.argument("openstack_command", required=True, nargs=-1)
 def openstack(
     oidc_client_id,
@@ -329,10 +319,10 @@ def openstack(
 
 
 @click.command()
-@oidc_params
-@openstack_params
 @site_params
 @vo_params
+@oidc_params
+@openstack_params
 def openstack_int(
     oidc_client_id,
     oidc_client_secret,

fedcloudclient/sites.py

@@ -324,8 +324,8 @@ def env(
 ):
     """
     Generate OS environment variables for site.
-    Does not set token environment variable,
-    need to set separately (e.g. via oidc-token command)
+    May set also environment variable OS_ACCESS_TOKEN,
+    if access token is provided, otherwise print notification
     """
     if site in ALL_SITES_KEYWORDS:
         print("Cannot generate environment variables for ALL_SITES")