Merge branch 'release/1.5.0'

debian/changelog

@@ -1,3 +1,12 @@
+edi (1.5.0) bionic; urgency=medium
+
+  [ Matthias Lüscher ]
+  * Added "edi documentation render ..." command that will enable the
+    rendering of a decent release notes or other documentation file.
+    Unit testing and documentation will be added in a subsequent version. 
+
+ -- Matthias Luescher <matthias.luescher@schindler.com>  Thu, 09 Apr 2020 21:01:13 +0200
+
 edi (1.4.3) bionic; urgency=medium
 
   [ Matthias Lüscher ]

debian/control

@@ -13,6 +13,7 @@ Build-Depends: ansible,
                python3,
                python3-apt (>= 1),
                python3-argcomplete,
+               python3-dateutil,
                python3-debian,
                python3-gnupg,
                python3-jinja2,
@@ -40,6 +41,7 @@ Depends: ${misc:Depends},
          liblzma5,
          openssh-client,
          python3-apt (>= 1),
+         python3-dateutil,
          qemu-user-static,
          sudo,
          zstd,

docs/conf.py

@@ -55,8 +55,8 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.4.3'
-release = '1.4.3'
+version = '1.5.0'
+release = '1.5.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

edi/__init__.py

@@ -24,7 +24,7 @@
 import argcomplete
 import logging
 import requests
-from edi.commands import clean, config, image, lxc, qemu, target, version  # noqa: ignore=F401
+from edi.commands import clean, config, image, lxc, qemu, target, version, documentation  # noqa: ignore=F401
 from edi.lib.commandfactory import get_sub_commands, get_command
 from edi.lib.helpers import print_error_and_exit, FatalError
 from edi.lib.edicommand import EdiCommand

edi/commands/__init__.py

@@ -25,5 +25,6 @@
 from edi.commands.configcommands import configclean, configinit  # noqa: ignore=F401
 from edi.commands.targetcommands import targetconfigure  # noqa: ignore=F401
 from edi.commands.qemucommands import fetch, qemuclean  # noqa: ignore=F401
+from edi.commands.documentationcommands import render  # noqa: ignore=F401
 
-__all__ = ["config", "image", "lxc", "version", "clean", "target", "qemu"]
+__all__ = ["config", "image", "lxc", "version", "clean", "target", "qemu", "documentation"]

edi/commands/documentation.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2020 Matthias Luescher
+#
+# Authors:
+#  Matthias Luescher
+#
+# This file is part of edi.
+#
+# edi is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# edi is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with edi.  If not, see <http://www.gnu.org/licenses/>.
+
+from edi.lib.edicommand import EdiCommand
+
+
+class Documentation(EdiCommand):
+
+    @classmethod
+    def advertise(cls, subparsers):
+        help_text = "run documentation related operations"
+        description_text = "Run commands related to edi documentation."
+        parser = subparsers.add_parser(cls._get_short_command_name(),
+                                       help=help_text,
+                                       description=description_text)
+
+        cls._add_sub_commands(parser)
+
+    def run_cli(self, cli_args):
+        self._run_sub_command_cli(cli_args)

edi/commands/documentationcommands/__init__.py

@@ -0,0 +1 @@
+__all__ = ["render"]

edi/commands/documentationcommands/render.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2020 Matthias Luescher
+#
+# Authors:
+#  Matthias Luescher
+#
+# This file is part of edi.
+#
+# edi is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# edi is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with edi.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+import argparse
+import logging
+from edi.commands.documentation import Documentation
+from edi.lib.helpers import print_success
+from edi.lib.documentationsteprunner import DocumentationStepRunner
+
+
+def readable_directory(directory):
+    if not os.path.isdir(directory):
+        raise argparse.ArgumentTypeError("directory '{}' does not exist".format(directory))
+    if not os.access(directory, os.R_OK):
+        raise argparse.ArgumentTypeError("directory '{}' is not readable".format(directory))
+    return directory
+
+
+def valid_output_directory(directory):
+    if not os.path.isdir(directory):
+        raise argparse.ArgumentTypeError("output directory '{}' does not exist".format(directory))
+    if not os.access(directory, os.W_OK):
+        raise argparse.ArgumentTypeError("output directory '{}' is not writable".format(directory))
+
+    return directory
+
+
+class Render(Documentation):
+
+    def __init__(self):
+        super().__init__()
+        self.raw_input = None
+        self.rendered_output = None
+
+    @classmethod
+    def advertise(cls, subparsers):
+        help_text = "render the project documentation"
+        description_text = "Render the project documentation."
+        parser = subparsers.add_parser(cls._get_short_command_name(),
+                                       help=help_text,
+                                       description=description_text)
+        exclusive_group = cls._offer_options(parser, introspection=True, clean=False)
+        exclusive_group.add_argument('--clean', action="store_true",
+                                     help='clean the artifacts that got produced by this command')
+        parser.add_argument('raw_input', type=readable_directory,
+                            help="directory containing the input files")
+        parser.add_argument('rendered_output', type=valid_output_directory,
+                            help="directory receiving the output files")
+        cls._require_config_file(parser)
+
+    @staticmethod
+    def _unpack_cli_args(cli_args):
+        return [cli_args.raw_input, cli_args.rendered_output, cli_args.config_file]
+
+    def run_cli(self, cli_args):
+        self._dispatch(*self._unpack_cli_args(cli_args), run_method=self._get_run_method(cli_args))
+
+    def dry_run(self, raw_input, rendered_output, config_file):
+        return self._dispatch(raw_input, rendered_output, config_file, run_method=self._dry_run)
+
+    def _dry_run(self):
+        plugins = DocumentationStepRunner(self.config, self.raw_input, self._result()).get_plugin_report()
+        return plugins
+
+    def run(self, raw_input, rendered_output, config_file):
+        return self._dispatch(raw_input, rendered_output, config_file, run_method=self._run)
+
+    def _run(self):
+        print("Going to render project documentation to '{}'.".format(self._result()))
+
+        documentation_step_runner = DocumentationStepRunner(self.config, self.raw_input, self._result())
+        documentation_step_runner.check_for_absence_of_output_files()
+        documentation_step_runner.run_all()
+        print_success("Rendered project documentation to '{}'.".format(self._result()))
+        return self._result()
+
+    def clean_recursive(self, raw_input, rendered_output, config_file, _):
+        self._dispatch(raw_input, rendered_output, config_file, run_method=self._clean)
+
+    def _clean(self):
+        documentation_step_runner = DocumentationStepRunner(self.config, self.raw_input, self._result())
+        documentation_step_runner.clean()
+
+    def _dispatch(self, raw_input, rendered_output, config_file, run_method):
+        self._setup_parser(config_file)
+        self.raw_input = os.path.abspath(raw_input)
+        self.rendered_output = os.path.abspath(rendered_output)
+
+        if os.getuid() == 0:
+            logging.warning('You should not not use the render command as root!')
+
+        return run_method()
+
+    def _result(self):
+        return self.rendered_output

edi/lib/configurationparser.py

@@ -319,7 +319,7 @@ def _merge_configurations(self, base, overlay):
                                                                                 "parameters")
 
         nested_elements = ["playbooks", "postprocessing_commands", "lxc_templates",
-                           "lxc_profiles", "shared_folders"]
+                           "lxc_profiles", "shared_folders", "documentation_steps"]
         for element in nested_elements:
             merged_config[element
                           ] = self._merge_nested_node(base, overlay,