Change: Improve CLI help for pontos-changelog and pontos-release

Explain the arguments of ponto-changelog and their purpose. Add
descriptions to the pontos-release sub-commands.

pontos/changelog/main.py

@@ -22,27 +22,31 @@
 
 def parse_args(args: Optional[Sequence[str]] = None) -> Namespace:
  parser = ArgumentParser(
- description="Conventional commits utility.",
+ description="Conventional commits utility. Create a changelog markdown "
+ " text from conventional commits between the current and next release.",
  prog="pontos-changelog",
  )
 
  parser.add_argument(
  "--config",
  "-C",
  type=Path,
- help="Conventional commits config file (toml), including conventions.",
+ help="Optional. Conventional commits config file (toml), including "
+ "conventions. If not provided defaults are used.",
  )
 
  parser.add_argument(
  "--project",
  required=True,
- help="The github project",
+ help="The github project. Used for building the links to the "
+ "repository.",
  )
 
  parser.add_argument(
  "--space",
  default="greenbone",
- help="User/Team name in github",
+ help="User/Team name in github. Used for building the links to the "
+ "repository",
  )
 
  parser.add_argument(
@@ -56,18 +60,22 @@ def parse_args(args: Optional[Sequence[str]] = None) -> Namespace:
 
  parser.add_argument(
  "--current-version",
- help="Current version before these changes",
+ help="Version to start looking for changes. All commits since this "
+ "releases are take into account for creating the changelog text.",
  )
 
  parser.add_argument(
  "--next-version",
+ "--release-version",
+ dest="next_version",
  help="The planned release version",
  )
 
  parser.add_argument(
  "--git-tag-prefix",
  default="v",
- help="Prefix for git tag versions. Default: %(default)s",
+ help="Prefix for git tag versions. Used to determine existing "
+ "releases. Default: %(default)s",
  )
 
  parser.add_argument(

pontos/release/parser.py

@@ -79,7 +79,10 @@ def parse_args(args) -> Tuple[Optional[str], Optional[str], Namespace]:
  )
 
  create_parser = subparsers.add_parser(
- "create", help="Create a new release", aliases=["release"]
+ "create",
+ aliases=["release"],
+ help="Create a new release",
+ description="Create a new release",
  )
  create_parser.set_defaults(func=create_release)
  create_parser.add_argument(
@@ -180,7 +183,9 @@ def parse_args(args) -> Tuple[Optional[str], Optional[str], Namespace]:
  )
 
  sign_parser = subparsers.add_parser(
- "sign", help="Create signatures for an existing release"
+ "sign",
+ help="Create signatures for an existing release",
+ description="Create signatures for an existing release",
  )
  sign_parser.set_defaults(func=sign)
  sign_parser.add_argument(
@@ -238,6 +243,8 @@ def parse_args(args) -> Tuple[Optional[str], Optional[str], Namespace]:
  "show",
  help="Show release information about the current release version and "
  "determine the next release version",
+ description="Show release information about the current release "
+ "version and determine the next release version",
  )
  show_parser.set_defaults(func=show)
  show_parser.add_argument(