feat(init): add a subcommand to create an example config

doc/args.rst

@@ -35,7 +35,8 @@ via ``python3.7 -m universum``.
         | * -f='test 1:!unit test 1'    - run all steps with 'test 1' substring in their names except those
          containing 'unit test 1'
 
-    {poll,submit,nonci,github-handler} : @replace
+    {create-config,poll,submit,nonci,github-handler} : @replace
+        | :doc:`universum init <create_config>`
         | :doc:`universum poll <args_poll>`
         | :doc:`universum submit <args_submit>`
         | :doc:`universum nonci <args_nonci>`

doc/configuring.rst

@@ -23,6 +23,9 @@ to this module in `config_path` member of its input settings.
     The project is free to use whatever it needs in the configuration file; just remember,
     all the calculations are done on config processing, not step execution.
 
+To :doc:`create an example config and get a command to launch it with Universum <init>`,
+run ``python3.7 -m universum init``.
+
 
 Project configuration
 ---------------------

doc/index.rst

@@ -28,3 +28,8 @@ The goal of this project is to provide unified approach for adding continuous in
 to any project. It currently supports Perforce, Git, Gerrit, Swarm, Jenkins and TeamCity.
 
 Sometimes `Universum` system can be referred to as the framework or just CI.
+
+To install Universum, make sure to :doc:`meet prerequisites <prerequisites>` and then simply run
+``pip3.7 install -U universum`` from command line.
+
+To :doc:`create an example config and execute it with Universum <init>`, run ``python3.7 -m universum init``.

doc/init.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+Initialize Universum
+--------------------
+
+If you have Universum installed via ``pip3.7 install -U universum`` or downloaded it from GitHub and changed
+working directory to project root, run ``python3.7 -m universum init`` to create an example configuration file,
+that can be :doc:`updated according to your project needs <configuring>` later.
+
+Running this command will not only create a configuration file, but will also provide you with a command line to
+execute it with Universum.

tests/test_create_config.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+import subprocess
+
+
+def test_create_config():
+    result = subprocess.run(["python3.7", "-m", "universum", "init"], capture_output=True, check=True)
+    new_command = ''
+    for line in result.stdout.splitlines():
+        if line.startswith(b'$ '):           # result.stdout is a byte string
+            new_command = line.lstrip(b'$ ')
+    new_result = subprocess.run(new_command.split(), capture_output=True, check=True)
+    Path(".universum.py").unlink()
+    artifacts = Path("artifacts")
+    artifacts.joinpath("CONFIGS_DUMP.txt").unlink()
+    artifacts.rmdir()
+    assert 'Hello world' in str(new_result.stdout)

universum/__main__.py

@@ -5,6 +5,7 @@
 from . import __version__, __title__
 from .api import Api
 from .github_handler import GithubHandler
+from .config_creator import ConfigCreator
 from .lib.ci_exception import SilentAbortException
 from .lib.gravity import define_arguments_recursive, construct_component
 from .lib.module_arguments import ModuleArgumentParser, ModuleNamespace, IncorrectParameterError
@@ -23,7 +24,7 @@ def define_arguments() -> ModuleArgumentParser:
     define_arguments_recursive(Main, parser)
 
     subparsers = parser.add_subparsers(title="Additional commands",
-                                       metavar="{poll,submit,nonci,github-handler}",
+                                       metavar="{init,poll,submit,nonci,github-handler}",
                                        help="Use 'universum <subcommand> --help' for more info")
 
     def define_command(klass, command):
@@ -33,6 +34,7 @@ def define_command(klass, command):
         define_arguments_recursive(klass, command_parser)
 
     define_command(Api, "api")
+    define_command(ConfigCreator, "init")
     define_command(Poll, "poll")
     define_command(Submit, "submit")
     define_command(Nonci, "nonci")

universum/api.py

@@ -1,12 +1,9 @@
-from types import TracebackType
-from typing import Optional
-
 import sys
 
 from .modules.api_support import ApiSupport
+from .modules.output.output import MinimalOut
 from .lib.gravity import Module, Dependency
 from .lib.module_arguments import ModuleArgumentParser
-from .lib.utils import format_traceback
 
 __all__ = ["Api"]
 
@@ -28,21 +25,7 @@ def __init__(self, *args, **kwargs) -> None:
             sys.stderr.write(str(error) + '\n')
             sys.exit(2)
 
-        class MinimalOut:
-            @staticmethod
-            def log(line: str) -> None:
-                pass
-
-            @staticmethod
-            def report_build_problem(problem: str) -> None:
-                pass
-
-            @staticmethod
-            def log_exception(exc: Exception) -> None:
-                ex_traceback: Optional[TracebackType] = sys.exc_info()[2]
-                sys.stderr.write("Unexpected error.\n" + format_traceback(exc, ex_traceback))
-
-        self.out = MinimalOut()
+        self.out = MinimalOut(silent=True)
 
     def execute(self) -> None:
         if self.settings.action == "file-diff":

universum/config_creator.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from .modules.output.output import MinimalOut
+from .lib.gravity import Module
+__all__ = ["ConfigCreator"]
+
+
+class ConfigCreator(Module):
+    description: str = "Create a dummy project"
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.out = MinimalOut()
+
+    def execute(self) -> None:
+        config_name = ".universum.py"
+        self.out.log(f"Creating an example configuration file '{config_name}'")
+
+        config = Path(config_name)
+        config.write_text("""#!/usr/bin/env python3.7
+
+from universum.configuration_support import Variations
+
+configs = Variations([dict(name='Show directory contents', command=['ls', '-la']),
+                      dict(name='Print a line', command=['bash', '-c', 'echo Hello world'])])
+
+if __name__ == '__main__':
+    print(configs.dump())
+""")
+        self.out.log("To run with Universum, execute the following command:\n"
+                     "$ python3.7 -m universum nonci --launcher-config-path={}".format(config_name))
+
+    def finalize(self) -> None:
+        pass

universum/modules/output/output.py

@@ -1,12 +1,15 @@
-from typing import ClassVar, Union
+import sys
+from types import TracebackType
+from typing import ClassVar, Optional, Union
 
 from ...lib.gravity import Module, Dependency
 from ...lib import utils
 from .terminal_based_output import TerminalBasedOutput
 from .teamcity_output import TeamcityOutput
 
 __all__ = [
-    "HasOutput"
+    "HasOutput",
+    "MinimalOut"
 ]
 
 
@@ -70,3 +73,21 @@ class HasOutput(Module):
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self.out: Output = self.out_factory()
+
+
+class MinimalOut:
+    def __init__(self, silent=False):
+        self.silent = silent
+
+    def log(self, line: str) -> None:
+        if not self.silent:
+            print(line)
+
+    @staticmethod
+    def report_build_problem(problem: str) -> None:
+        pass
+
+    @staticmethod
+    def log_exception(exc: Exception) -> None:
+        ex_traceback: Optional[TracebackType] = sys.exc_info()[2]
+        sys.stderr.write("Unexpected error.\n" + utils.format_traceback(exc, ex_traceback))