cli: Add more info to help and update readme

README.md

@@ -13,9 +13,9 @@ There are four checks available right now - the `manifest` check, the
   as input.
 - The `appstream` check expects a [Metainfo file](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/#path-and-filename)
   as input.
-- The `builddir` check expects a build directory generated by
-  Flatpak Builder as input.
-- The `repo` check expects an OSTree repository generated by Flatpak
+- The `builddir` check expects a build directory generated by Flatpak
+  Builder as input.
+- The `repo` check expects an OSTree repository exported by Flatpak
   Builder as input.
 
 The last two are created when [building the application](https://docs.flathub.org/docs/for-app-authors/submission#build-and-install)
@@ -145,7 +145,7 @@ poetry run mypy .
 
 A pre-commit hook is provided to automate the formatting and linting:
 
-```
+```sh
 poetry run pre-commit install
 poetry run pre-commit run --all-files
 
@@ -175,22 +175,27 @@ NO_CLEAN_UP=1 ./tests/flatmanager.sh
 ## Usage
 
 ```
-usage: flatpak-builder-lint [-h] [--version] [--exceptions] [--appid APPID] [--cwd] [--ref REF] {builddir,repo,manifest,appstream} path
+usage: flatpak-builder-lint [-h] [--version] [--exceptions] [--appid APPID] [--cwd] [--ref REF] {appstream,manifest,builddir,repo} path
 
 A linter for Flatpak builds and flatpak-builder manifests
 
 positional arguments:
-  {builddir,repo,manifest,appstream}
-                        type of artifact to lint
-  path                  path to artifact
+  {appstream,manifest,builddir,repo}
+                        Type of artifact to lint
+
+                        appstream expects a MetaInfo file
+                        manifest expects a flatpak-builder manifest
+                        builddir expects a flatpak-builder build directory
+                        repo expects an OSTree repo exported by flatpak-builder
+  path                  Path to the artifact
 
 options:
-  -h, --help            show this help message and exit
-  --version             show program's version number and exit
-  --exceptions          skip allowed warnings or errors
-  --appid APPID         override app ID
-  --cwd                 override the path parameter with current working directory
-  --ref REF             override the primary ref detection
+  -h, --help            Show this help message and exit
+  --version             Show the version number and exit
+  --exceptions          Skip warnings or errors added to exceptions. Exceptions must be submitted to Flathub or be available in exceptions.json locally
+  --appid APPID         Override the app ID
+  --cwd                 Override the path parameter with current working directory
+  --ref REF             Override the primary ref detection
 
 If you consider the detected issues incorrect, please report it here: https://github.com/flathub/flatpak-builder-lint
 ```

flatpak_builder_lint/cli.py

@@ -5,6 +5,7 @@
 import os
 import pkgutil
 import sys
+import textwrap
 
 import sentry_sdk
 
@@ -135,34 +136,62 @@ def run_checks(
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="A linter for Flatpak builds and flatpak-builder manifests",
-        epilog="If you consider the detected issues incorrect, please report it here: https://github.com/flathub/flatpak-builder-lint",  # noqa: E501
+        epilog="If you consider the detected issues incorrect, please report it here: https://github.com/flathub/flatpak-builder-lint",
+        formatter_class=argparse.RawTextHelpFormatter,
+        add_help=False,
     )
     parser.add_argument(
-        "--version", action="version", version=f"flatpak-builder-lint {__version__}"
+        "-h",
+        "--help",
+        action="help",
+        default=argparse.SUPPRESS,
+        help="Show this help message and exit",
     )
-    parser.add_argument("--exceptions", help="skip allowed warnings or errors", action="store_true")
-    parser.add_argument("--appid", help="override app ID", type=str, nargs=1)
+    parser.add_argument(
+        "--version",
+        action="version",
+        help="Show the version number and exit",
+        version=f"flatpak-builder-lint {__version__}",
+    )
+    parser.add_argument(
+        "--exceptions",
+        help="Skip warnings or errors added to exceptions. Exceptions must be submitted to Flathub"
+        + " or be available in exceptions.json locally",
+        action="store_true",
+    )
+    parser.add_argument("--appid", help="Override the app ID", type=str, nargs=1)
     parser.add_argument(
         "--cwd",
-        help="override the path parameter with current working directory",
+        help="Override the path parameter with current working directory",
         action="store_true",
     )
     parser.add_argument(
         "--ref",
-        help="override the primary ref detection",
+        help="Override the primary ref detection",
         type=str,
         nargs=1,
         default=None,
     )
 
     parser.add_argument(
         "type",
-        help="type of artifact to lint",
-        choices=["builddir", "repo", "manifest", "appstream"],
+        help=textwrap.dedent("""\
+        Type of artifact to lint
+
+        appstream expects a MetaInfo file
+        manifest expects a flatpak-builder manifest
+        builddir expects a flatpak-builder build directory
+        repo expects an OSTree repo exported by flatpak-builder"""),
+        choices=[
+            "appstream",
+            "manifest",
+            "builddir",
+            "repo",
+        ],
     )
     parser.add_argument(
         "path",
-        help="path to artifact",
+        help="Path to the artifact",
         type=str,
         nargs=1,
     )