docs: add missing help test to CLIs and make them work with sphinx

Signed-off-by: Eike Waldt <waldt@b1-systems.de>
On-behalf-of: SAP <eike.waldt@sap.com>

Author: yeoldegrove

src/gardenlinux/features/__main__.py

@@ -39,33 +39,93 @@
 """
 
 
-def main() -> None:
+def get_parser() -> argparse.ArgumentParser:
     """
-    gl-features-parse main()
+    Get the argument parser for gl-features-parse.
+    Used for documentation generation.
 
-    :since: 0.7.0
+    :return: ArgumentParser instance
+    :since: 0.10.9
     """
+    parser = argparse.ArgumentParser(
+        description="Parse and extract information from GardenLinux features."
+    )
 
-    parser = argparse.ArgumentParser()
-
-    parser.add_argument("--arch", dest="arch")
-    parser.add_argument("--cname", dest="cname", required=True)
-    parser.add_argument("--commit", dest="commit")
-    parser.add_argument("--feature-dir", default="features")
-    parser.add_argument("--release-file", dest="release_file")
-    parser.add_argument("--default-arch", dest="default_arch")
-    parser.add_argument("--default-version", dest="default_version")
-    parser.add_argument("--version", dest="version")
+    parser.add_argument(
+        "--arch",
+        dest="arch",
+        help="Target architecture (e.g., amd64, arm64). Overrides architecture from cname.",
+    )
+    parser.add_argument(
+        "--cname",
+        dest="cname",
+        required=True,
+        help="Canonical name (cname) to parse. Must be a valid GardenLinux canonical name.",
+    )
+    parser.add_argument(
+        "--commit",
+        dest="commit",
+        help="Git commit hash. If not specified, will be read from COMMIT file or release file.",
+    )
+    parser.add_argument(
+        "--feature-dir",
+        default="features",
+        help="Path to the features directory (default: 'features'). Either --feature-dir or --release-file must be provided.",
+    )
+    parser.add_argument(
+        "--release-file",
+        dest="release_file",
+        help="Path to a release file containing cname metadata. Either --feature-dir or --release-file must be provided.",
+    )
+    parser.add_argument(
+        "--default-arch",
+        dest="default_arch",
+        help="Default architecture to use if architecture cannot be determined from cname or other sources.",
+    )
+    parser.add_argument(
+        "--default-version",
+        dest="default_version",
+        help="Default version to use if version cannot be determined from files or other sources.",
+    )
+    parser.add_argument(
+        "--version",
+        dest="version",
+        help="Version string. If not specified, will be read from VERSION file or release file.",
+    )
 
     parser.add_argument(
         "--ignore",
         dest="ignore",
         type=lambda arg: set([f for f in arg.split(",") if f]),
         default=set(),
+        help="Comma-separated list of features to ignore when processing (e.g., 'feature1,feature2').",
     )
 
-    parser.add_argument("type", nargs="?", choices=_ARGS_TYPE_ALLOWED, default="cname")
+    parser.add_argument(
+        "type",
+        nargs="?",
+        choices=_ARGS_TYPE_ALLOWED,
+        default="cname",
+        help="Type of output to generate. Choices: {}. Default: 'cname'.".format(
+            ", ".join(_ARGS_TYPE_ALLOWED)
+        ),
+    )
+    return parser
+
+
+# Parser object for documentation generation
+parser = get_parser()
+parser.prog = "gl-features-parse"
+
+
+def main() -> None:
+    """
+    gl-features-parse main()
+
+    :since: 0.7.0
+    """
 
+    parser = get_parser()
     args = parser.parse_args()
 
     assert bool(args.feature_dir) or bool(args.release_file), (

src/gardenlinux/features/cname_main.py

@@ -18,21 +18,57 @@
 from .parser import Parser
 
 
+def get_parser() -> argparse.ArgumentParser:
+    """
+    Get the argument parser for gl-cname.
+    Used for documentation generation.
+
+    :return: ArgumentParser instance
+    :since: 1.0.0
+    """
+    parser = argparse.ArgumentParser(
+        description="Generate a canonical name (cname) from feature sets."
+    )
+    parser.add_argument(
+        "--arch",
+        dest="arch",
+        help="Target architecture (e.g., amd64, arm64). If not specified, will be determined from the cname or feature set.",
+    )
+    parser.add_argument(
+        "--commit",
+        dest="commit",
+        help="Git commit hash. If not specified, will be read from COMMIT file in the GardenLinux root directory.",
+    )
+    parser.add_argument(
+        "--feature-dir",
+        default="features",
+        help="Path to the features directory (default: 'features').",
+    )
+    parser.add_argument(
+        "--version",
+        dest="version",
+        help="Version string. If not specified, will be read from VERSION file in the GardenLinux root directory.",
+    )
+    parser.add_argument(
+        "cname",
+        help="Canonical name (cname) to process. Must be a valid GardenLinux canonical name format.",
+    )
+    return parser
+
+
+# Parser object for documentation generation
+parser = get_parser()
+parser.prog = "gl-cname"
+
+
 def main() -> None:
     """
     gl-cname main()
 
     :since: 0.7.0
     """
 
-    parser = argparse.ArgumentParser()
-
-    parser.add_argument("--arch", dest="arch")
-    parser.add_argument("--commit", dest="commit")
-    parser.add_argument("--feature-dir", default="features")
-    parser.add_argument("--version", dest="version")
-    parser.add_argument("cname")
-
+    parser = get_parser()
     args = parser.parse_args()
 
     re_match = re.match(

src/gardenlinux/flavors/__main__.py

@@ -47,14 +47,14 @@ def generate_markdown_table(combinations: List[Tuple[Any, str]]) -> str:
     return table
 
 
-def parse_args() -> Namespace:
+def get_parser() -> ArgumentParser:
     """
-    Parses arguments used for main()
+    Get the argument parser for gl-flavors-parse.
+    Used for documentation generation.
 
-    :return: (object) Parsed argparse.ArgumentParser namespace
-    :since:  0.7.0
+    :return: ArgumentParser instance
+    :since: 1.0.0
     """
-
     parser = ArgumentParser(description="Parse flavors.yaml and generate combinations.")
 
     parser.add_argument(
@@ -122,7 +122,22 @@ def parse_args() -> Namespace:
         help="Generate a markdown table by platform.",
     )
 
-    return parser.parse_args()
+    return parser
+
+
+# Parser object for documentation generation
+parser = get_parser()
+parser.prog = "gl-flavors-parse"
+
+
+def parse_args() -> Namespace:
+    """
+    Parses arguments used for main()
+
+    :return: (object) Parsed argparse.ArgumentParser namespace
+    :since:  0.7.0
+    """
+    return get_parser().parse_args()
 
 
 def main() -> None:

src/gardenlinux/github/release/__main__.py

@@ -14,35 +14,131 @@
 LOGGER = LoggerSetup.get_logger("gardenlinux.github", logging.INFO)
 
 
-def main() -> None:
-    parser = argparse.ArgumentParser(description="GitHub Release Script")
-    subparsers = parser.add_subparsers(dest="command")
-
-    create_parser = subparsers.add_parser("create")
-    create_parser.add_argument("--owner", default="gardenlinux")
-    create_parser.add_argument("--repo", default="gardenlinux")
-    create_parser.add_argument("--tag", required=True)
-    create_parser.add_argument("--name")
-    create_parser.add_argument("--body", required=True)
-    create_parser.add_argument("--commit")
-    create_parser.add_argument("--pre-release", action="store_true", default=True)
-    create_parser.add_argument("--latest", action="store_true", default=False)
-
-    create_parser_gl = subparsers.add_parser("create-with-gl-release-notes")
-    create_parser_gl.add_argument("--owner", default="gardenlinux")
-    create_parser_gl.add_argument("--repo", default="gardenlinux")
-    create_parser_gl.add_argument("--tag", required=True)
-    create_parser_gl.add_argument("--commit", required=True)
-    create_parser_gl.add_argument("--latest", action="store_true", default=False)
-    create_parser_gl.add_argument("--dry-run", action="store_true", default=False)
-
-    upload_parser = subparsers.add_parser("upload")
-    upload_parser.add_argument("--owner", default="gardenlinux")
-    upload_parser.add_argument("--repo", default="gardenlinux")
-    upload_parser.add_argument("--release_id", required=True)
-    upload_parser.add_argument("--file_path", required=True)
-    upload_parser.add_argument("--dry-run", action="store_true", default=False)
+def get_parser() -> argparse.ArgumentParser:
+    """
+    Get the argument parser for gl-gh-release.
+    Used for documentation generation.
+
+    :return: ArgumentParser instance
+    :since: 1.0.0
+    """
+    parser = argparse.ArgumentParser(description="Create and manage GitHub releases.")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    create_parser = subparsers.add_parser(
+        "create", help="Create a new GitHub release."
+    )
+    create_parser.add_argument(
+        "--owner",
+        default="gardenlinux",
+        help="GitHub repository owner (default: 'gardenlinux').",
+    )
+    create_parser.add_argument(
+        "--repo",
+        default="gardenlinux",
+        help="GitHub repository name (default: 'gardenlinux').",
+    )
+    create_parser.add_argument(
+        "--tag", required=True, help="Git tag name for the release (required)."
+    )
+    create_parser.add_argument(
+        "--name", help="Release name/title. If not specified, the tag will be used."
+    )
+    create_parser.add_argument(
+        "--body", required=True, help="Release notes/description body (required)."
+    )
+    create_parser.add_argument(
+        "--commit",
+        help="Git commit hash. If not specified, the tag will be used to find the commit.",
+    )
+    create_parser.add_argument(
+        "--pre-release",
+        action="store_true",
+        default=True,
+        help="Mark the release as a pre-release (default: True).",
+    )
+    create_parser.add_argument(
+        "--latest",
+        action="store_true",
+        default=False,
+        help="Mark this release as the latest release (default: False).",
+    )
+
+    create_parser_gl = subparsers.add_parser(
+        "create-with-gl-release-notes",
+        help="Create a GitHub release with auto-generated GardenLinux release notes.",
+    )
+    create_parser_gl.add_argument(
+        "--owner",
+        default="gardenlinux",
+        help="GitHub repository owner (default: 'gardenlinux').",
+    )
+    create_parser_gl.add_argument(
+        "--repo",
+        default="gardenlinux",
+        help="GitHub repository name (default: 'gardenlinux').",
+    )
+    create_parser_gl.add_argument(
+        "--tag", required=True, help="Git tag name for the release (required)."
+    )
+    create_parser_gl.add_argument(
+        "--commit",
+        required=True,
+        help="Git commit hash used to generate release notes (required).",
+    )
+    create_parser_gl.add_argument(
+        "--latest",
+        action="store_true",
+        default=False,
+        help="Mark this release as the latest release (default: False).",
+    )
+    create_parser_gl.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="Perform a dry run without actually creating the release.",
+    )
+
+    upload_parser = subparsers.add_parser(
+        "upload", help="Upload a file to an existing GitHub release."
+    )
+    upload_parser.add_argument(
+        "--owner",
+        default="gardenlinux",
+        help="GitHub repository owner (default: 'gardenlinux').",
+    )
+    upload_parser.add_argument(
+        "--repo",
+        default="gardenlinux",
+        help="GitHub repository name (default: 'gardenlinux').",
+    )
+    upload_parser.add_argument(
+        "--release_id",
+        required=True,
+        help="GitHub release ID to upload the file to (required).",
+    )
+    upload_parser.add_argument(
+        "--file_path",
+        required=True,
+        help="Path to the file to upload (required).",
+    )
+    upload_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="Perform a dry run without actually uploading the file.",
+    )
 
+    return parser
+
+
+# Parser object for documentation generation
+parser = get_parser()
+parser.prog = "gl-gh-release"
+
+
+def main() -> None:
+    parser = get_parser()
     args = parser.parse_args()
 
     if args.command == "create":