refactor(cli): remove CommandParserBuilder, simplify main()

WHAT:

Based on the refactoring done in the previous PRs, the StrictDoc CLI commands
are now modelled using Command pattern.

This change refactors the `cli/` files a little further:

- Merge the content of CommandParserBuilder into SDocArgsParser.
- Declare the registry of valid StrictDoc commands in the
  `strictdoc/cli/main.py` file directly which gives a good idea of the overall CLI interface.
- Simplify the logic of the main()-related functions.

WHY:

- This change further reduces the number of classes and code lines needed to
  parse the CLI arguments and call the right StrictDoc commands, improving the
  readability and maintainability of the code.

HOW:

Smaller knowledge bits:

- The creation of the argument parser is now placed as the very first
  step of StrictDoc invocation. This is done to avoid any further tool
  configuration and progress if the arguments are incorrect.
- With the simplified code, it is now also clear that printing the total
  execution time for all commands does not make too much sense. For
  example, the "about" and "version" commands do not really need the
  total execution time to be printed. This issue existed before the
  refactoring but with the reduced code size it became even more
  obvious. Improving this will be another work item outside this change.

Author: stanislaw

docs/strictdoc_21_L2_StrictDoc_Requirements.sdoc

@@ -1710,9 +1710,6 @@ RELATIONS:
 - TYPE: File
   FORMAT: Sourcecode
   VALUE: strictdoc/cli/main.py
-- TYPE: File
-  FORMAT: Sourcecode
-  VALUE: strictdoc/cli/command_parser_builder.py
 - TYPE: File
   FORMAT: Sourcecode
   VALUE: strictdoc/cli/cli_arg_parser.py

strictdoc/cli/cli_arg_parser.py

@@ -1,15 +1,42 @@
 import argparse
-from typing import Any, Dict, Optional
+import sys
+from typing import Any, Dict, NoReturn
 
-from strictdoc.cli.command_parser_builder import (
-    COMMAND_REGISTRY,
-    CommandParserBuilder,
-)
+from strictdoc import __version__
 from strictdoc.helpers.cast import assert_cast
 from strictdoc.helpers.parallelizer import Parallelizer
 
 
+def formatter(prog: str) -> argparse.RawTextHelpFormatter:
+    return argparse.RawTextHelpFormatter(
+        prog, indent_increment=2, max_help_position=4, width=80
+    )
+
+
+class SDocArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        print(f"{self.prog}: error: {message}", file=sys.stderr)  # noqa: T201
+        print("")  # noqa: T201
+        print("Further help:")  # noqa: T201
+        print(  # noqa: T201
+            "'strictdoc -h/--help' provides a general overview of available commands."
+        )
+        print(  # noqa: T201
+            "'strictdoc <command> -h/--help' provides command-specific help."
+        )
+        sys.exit(2)
+
+
 class SDocArgsParser:
+    @classmethod
+    def create_sdoc_args_parser(
+        cls, registry: Dict[str, Any]
+    ) -> "SDocArgsParser":
+        parser = cls.build_argparse(registry)
+        args = parser.parse_args()
+        return cls(args, registry)
+
     def __init__(self, args: argparse.Namespace, registry: Dict[str, Any]):
         self.args: argparse.Namespace = args
         self.registry: Dict[str, Any] = registry
@@ -31,13 +58,61 @@ def run(self, parallelizer: Parallelizer) -> bool:
 
         return True
 
+    @classmethod
+    def build_argparse(cls, registry: Dict[str, Any]) -> SDocArgumentParser:
+        # https://stackoverflow.com/a/19476216/598057
+        main_parser = SDocArgumentParser(
+            prog="strictdoc",
+            add_help=True,
+            epilog=(
+                """
+                Further help: https://strictdoc.readthedocs.io/en/stable/
+                """
+            ),
+        )
 
-def create_sdoc_args_parser(
-    testing_args: Optional[argparse.Namespace] = None,
-) -> SDocArgsParser:
-    args = testing_args
-    if not args:
-        builder = CommandParserBuilder()
-        parser = builder.build()
-        args = parser.parse_args()
-    return SDocArgsParser(args, COMMAND_REGISTRY)
+        # The -v/--version has a special behavior that it still works when all
+        # commands are required == True.
+        # https://stackoverflow.com/a/12123598/598057
+        main_parser.add_argument(
+            "-v", "--version", action="version", version=__version__
+        )
+
+        main_parser.add_argument(
+            "--debug",
+            action="store_true",
+            default=False,
+            help="Enable more verbose printing of errors when they are encountered.",
+        )
+
+        command_subparsers = main_parser.add_subparsers(
+            title="command", dest="command"
+        )
+        command_subparsers.required = True
+
+        # Dynamically add subcommands
+        for name, cmd in registry.items():
+            if isinstance(cmd, dict):  # command family
+                family_parser = command_subparsers.add_parser(name)
+                family_subparsers = family_parser.add_subparsers(
+                    dest="subcommand"
+                )
+                family_subparsers.required = True
+                for subname, subcmd in cmd.items():
+                    sub_parser = family_subparsers.add_parser(
+                        subname,
+                        help=subcmd.HELP,
+                        description=subcmd.DETAILED_HELP,
+                        formatter_class=formatter,
+                    )
+                    subcmd.add_arguments(sub_parser)
+            else:
+                cmd_parser = command_subparsers.add_parser(
+                    name,
+                    help=cmd.HELP,
+                    description=cmd.DETAILED_HELP,
+                    formatter_class=formatter,
+                )
+                cmd.add_arguments(cmd_parser)
+
+        return main_parser

strictdoc/cli/command_parser_builder.py

@@ -6,7 +6,7 @@
 import multiprocessing
 import os
 import sys
-from typing import Optional
+from typing import Any, Dict, Optional
 
 strictdoc_root_path = os.path.abspath(
     os.path.join(os.path.dirname(__file__), "..", "..")
@@ -17,8 +17,14 @@
 from strictdoc import environment
 from strictdoc.cli.cli_arg_parser import (
     SDocArgsParser,
-    create_sdoc_args_parser,
 )
+from strictdoc.commands.about_command import AboutCommand
+from strictdoc.commands.export import ExportCommand
+from strictdoc.commands.import_excel import ImportExcelCommand
+from strictdoc.commands.import_reqif import ImportReqIFCommand
+from strictdoc.commands.manage_autouid_command import ManageAutoUIDCommand
+from strictdoc.commands.server import ServerCommand
+from strictdoc.commands.version_command import VersionCommand
 from strictdoc.helpers.coverage import register_code_coverage_hook
 from strictdoc.helpers.exception import (
     ExceptionInfo,
@@ -27,17 +33,27 @@
 from strictdoc.helpers.parallelizer import Parallelizer
 from strictdoc.helpers.timing import measure_performance
 
+COMMAND_REGISTRY: Dict[str, Any] = {
+    "about": AboutCommand,
+    "export": ExportCommand,
+    "import": {"excel": ImportExcelCommand, "reqif": ImportReqIFCommand},
+    "manage": {"auto-uid": ManageAutoUIDCommand},
+    "server": ServerCommand,
+    "version": VersionCommand,
+}
 
-def _main_internal(parallelizer: Parallelizer, parser: SDocArgsParser) -> None:
-    register_code_coverage_hook()
-
-    if parser.run(parallelizer):
-        return
 
-    raise NotImplementedError
+def _main() -> None:
+    # The parser can raise when no arguments or incorrect arguments are provided.
+    try:
+        parser = SDocArgsParser.create_sdoc_args_parser(COMMAND_REGISTRY)
+    except Exception as exception_:
+        print(f"error: {str(exception_)}", flush=True)  # noqa: T201
+        sys.exit(1)
 
+    if parser.is_debug_mode():
+        environment.is_debug_mode = True
 
-def _main() -> None:
     # Ensure that multiprocessing.freeze_support() is called in a frozen
     # application
     # https://github.com/pyinstaller/pyinstaller/issues/7438
@@ -63,25 +79,14 @@ def _main() -> None:
         1, "w", encoding="utf-8", closefd=False
     )
 
-    enable_parallelization = "--no-parallelization" not in sys.argv
-
-    # NOTE: The parser can exit before the _main starts when no arguments
-    #       or incorrect arguments are provided. In those cases, it is still
-    #       important that the parallelizer is correctly shut down.
-    try:
-        parser = create_sdoc_args_parser()
-    except Exception as exception_:
-        print(f"error: {str(exception_)}", flush=True)  # noqa: T201
-        sys.exit(1)
-
-    if parser.is_debug_mode():
-        environment.is_debug_mode = True
+    register_code_coverage_hook()
 
+    enable_parallelization = "--no-parallelization" not in sys.argv
     parallelizer = Parallelizer.create(enable_parallelization)
 
     exception_info: Optional[ExceptionInfo] = None
     try:
-        _main_internal(parallelizer, parser)
+        parser.run(parallelizer)
     except StrictDocChildProcessException as exception_info_:
         exception_info = exception_info_.exception_info
     except Exception as exception_:

strictdoc/cli/main.py

@@ -32,6 +32,6 @@ def run(self, parallelizer: Parallelizer) -> None:  # noqa: ARG002
             "Docs:    https://strictdoc.readthedocs.io/en/stable/"
         )
         print(  # noqa: T201
-            "Github:  https://github.com/strictdoc-project/strictdoc"
+            "GitHub:  https://github.com/strictdoc-project/strictdoc"
         )
         print("License: Apache 2")  # noqa: T201

strictdoc/commands/about_command.py

@@ -9,8 +9,9 @@
 from strictdoc.backend.sdoc.models.document import SDocDocument
 from strictdoc.backend.sdoc.models.node import SDocNode
 from strictdoc.cli.cli_arg_parser import (
-    create_sdoc_args_parser,
+    SDocArgsParser,
 )
+from strictdoc.cli.main import COMMAND_REGISTRY
 from strictdoc.commands.export_config import ExportCommandConfig
 from strictdoc.core.document_iterator import SDocDocumentIterator
 from strictdoc.core.graph.abstract_bucket import ALL_EDGES
@@ -119,7 +120,7 @@ def find_doc(self, name):
 
 
 if __name__ == "__main__":
-    parser = create_sdoc_args_parser()
+    parser = SDocArgsParser.create_sdoc_args_parser(COMMAND_REGISTRY)
     project_config: ProjectConfig
 
     export_config: ExportCommandConfig = ExportCommandConfig(**vars(parser.args))

tests/integration/scripting_examples/questionnaires/02_user_provided_example/export_questionnaires.py

@@ -1,12 +1,13 @@
 from strictdoc.cli.cli_arg_parser import (
-    CommandParserBuilder,
+    SDocArgsParser,
 )
+from strictdoc.cli.main import COMMAND_REGISTRY
 
 FAKE_STRICTDOC_ROOT_PATH = "/tmp/strictdoc-123"
 
 
 def cli_args_parser():
-    return CommandParserBuilder().build()
+    return SDocArgsParser.build_argparse(COMMAND_REGISTRY)
 
 
 def test_export_01_minimal():