Add documentation for commodore tool command group

Author: simu

commodore/cli/tool.py

@@ -16,6 +16,11 @@
 @options.pass_config
 @options.github_token
 def tool_group(config: Config, verbose: int, github_token: str):
+    """Commands to manage required external tools.
+
+    Currently, `helm`, jsonnet-bundler/`jb`, and `kustomize` are required
+    external tools.
+    """
     config.update_verbosity(verbose)
     config.managed_tools = tools.load_state()
     config.github_token = github_token
@@ -32,6 +37,16 @@ def tool_group(config: Config, verbose: int, github_token: str):
     help="Query GitHub API to get latest version",
 )
 def tool_list(config: Config, verbose: int, github_token: str, version_check: bool):
+    """List the version, location and management state of the required external tools.
+
+    Currently, `helm`, jsonnet-bundler/`jb`, and `kustomize` are required
+    external tools. By default, the command also queries the GitHub API to
+    determine the latest available version of each tool and indicates whether an
+    update is available.
+
+    Optionally, the command accepts a GitHub personal access token (PAT) to
+    avoid running into the fairly strict unauthenticated GitHub rate limits.
+    """
     config.update_verbosity(verbose)
     config.github_token = github_token
     tools.list_tools(config, version_check)
@@ -45,12 +60,25 @@ def tool_list(config: Config, verbose: int, github_token: str, version_check: bo
     "--version",
     default=None,
     metavar="VERSION",
-    help="A custom version to install for the requested tool (by default the latest version is installed)",
+    help="A version to install for the requested tool. "
+    + "By default, the latest version is installed.",
 )
 @click.argument("tool")
 def tool_install(
     config: Config, verbose: int, tool: str, version: Optional[str], github_token: str
 ):
+    """Install one of the required tools in `$XDG_CACHE_DIR/commodore/tools`.
+
+    The command will fail for tools which are already managed by Commodore.
+
+    By default, the command will install the latest available tool version. For
+    `helm` and `kustomize`, the command downloads the official installation
+    scripts and executes them with appropriate arguments. For `jb`, the command
+    directly downloads the requested version from the GitHub release page.
+
+    Optionally, the command accepts a tool version to install. The command
+    accepts versions prefixed  with "v" and unprefixed versions.
+    """
     config.update_verbosity(verbose)
     config.github_token = github_token
     tools.install_tool(config, tool, version)
@@ -64,12 +92,26 @@ def tool_install(
     "--version",
     default=None,
     metavar="VERSION",
-    help="A custom version to install for the requested tool (by default the latest version is installed)",
+    help="A version to upgrade (or downgrade) to for the requested tool. "
+    + "By default, the tool is upgraded to the latest version.",
 )
 @click.argument("tool")
 def tool_upgrade(
     config: Config, verbose: int, tool: str, version: Optional[str], github_token: str
 ):
+    """Upgrade (or downgrade) one of the required tools in `$XDG_CACHE_DIR/commodore/tools`.
+
+    The command will fail for tools which aren't managed by Commodore yet.
+
+    By default, the command will upgrade the tool to the latest available
+    version. For `helm` and `kustomize`, the command downloads the official
+    installation scripts and executes them with appropriate arguments. For `jb`,
+    the command directly downloads the requested version from the GitHub release
+    page.
+
+    Optionally, the command accepts a tool version to upgrade (or downgrade) to.
+    The command accepts versions prefixed with "v" and unprefixed versions.
+    """
     config.update_verbosity(verbose)
     config.github_token = github_token
     tools.upgrade_tool(config, tool, version)

docs/modules/ROOT/pages/reference/cli.adoc

@@ -655,6 +655,37 @@ However, labels added by previous runs can't be removed since we've got no easy
   The component template version (Git tree-ish) to use.
   If not provided, the currently active template version will be used.
 
+== Tool List
+
+*--github-token* TEXT::
+  The GitHub access token to use when interacting with the GitHub API.
+  We recommend passing the token in environment variable `COMMODORE_GITHUB_TOKEN`.
+
+
+*--version-check / -V, --skip-version-check*::
+  Whether to query the GitHub API to get latest versions.
+
+== Tool Install
+
+*--github-token* TEXT::
+  The GitHub access token to use when interacting with the GitHub API.
+  We recommend passing the token in environment variable `COMMODORE_GITHUB_TOKEN`.
+
+*--version VERSION*::
+  Specify a version to install for the requested tool.
+  By default, the latest version is installed.
+
+
+== Tool Upgrade
+
+*--github-token* TEXT::
+  The GitHub access token to use when interacting with the GitHub API.
+  We recommend passing the token in environment variable `COMMODORE_GITHUB_TOKEN`.
+
+*--version VERSION*::
+  Specify a custom version to upgrade (or downgrade) to for the requested tool.
+  By default, tools are upgraded to the latest version.
+
 == Version
 
 Show extended version information for Commodore.

docs/modules/ROOT/pages/reference/commands.adoc

@@ -278,6 +278,47 @@ The command bases each PR on the default branch of the corresponding package rep
 The command requires a GitHub Access token with the 'public_repo' permission, which is required to create PRs on public repositories.
 If you want to manage private repos, the access token may require additional permissions.
 
+== Tool List
+
+  commodore tool list
+
+This command lists the version, location and management state of the required external tools.
+
+Currently, `helm`, jsonnet-bundler/`jb`, and `kustomize` are required external tools.
+By default, the command also queries the GitHub API to determine the latest available version of each tool and indicates whether an update is available.
+
+Optionally, the command accepts a GitHub personal access token (PAT) to avoid running into the fairly strict unauthenticated GitHub rate limits.
+
+== Tool Install
+
+  commodore tool install TOOL
+
+Install one of the required tools in `$XDG_CACHE_DIR/commodore/tools`.
+
+The command will fail for tools which are already managed by Commodore.
+
+By default, the command will install the latest available tool version.
+For `helm` and `kustomize`, the command downloads the official installation scripts and executes them with appropriate arguments.
+For `jb`, the command directly downloads the requested version from the GitHub release page.
+
+Optionally, the command accepts a tool version to install.
+The command accepts versions prefixed  with "v" and unprefixed versions.
+
+== Tool Upgrade
+
+  commodore tool upgrade TOOL
+
+Upgrade (or downgrade) one of the required tools in `$XDG_CACHE_DIR/commodore/tools`.
+
+The command will fail for tools which aren't managed by Commodore yet.
+
+By default, the command will upgrade the tool to the latest available version.
+For `helm` and `kustomize`, the command downloads the official installation scripts and executes them with appropriate arguments.
+For `jb`, the command directly downloads the requested version from the GitHub release page.
+
+Optionally, the command accepts a tool version to upgrade (or downgrade) to.
+The command accepts versions prefixed with "v" and unprefixed versions.
+
 == Version
 
   commodore version