language plugins

Author: acabarbaye

continuous_delivery_scripts/generate_docs.py

@@ -2,19 +2,16 @@
 # Copyright (C) 2020 Arm Mbed. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 #
-"""Generates documentation using Pdoc."""
+"""Generates documentation."""
+import argparse
+import logging
 import os
 import shutil
 import sys
-
-import argparse
-import logging
 from pathlib import Path
-from subprocess import check_call
-from typing import List
 
+from continuous_delivery_scripts.language_specifics import get_language_specifics
 from continuous_delivery_scripts.utils.configuration import configuration, ConfigurationVariable
-from continuous_delivery_scripts.utils.filesystem_helpers import TemporaryDirectory
 from continuous_delivery_scripts.utils.logging import log_exception
 
 logger = logging.getLogger(__name__)
@@ -26,40 +23,11 @@ def _clear_previous_docs(output_directory: Path) -> None:
         shutil.rmtree(str(output_directory))
 
 
-def _generate_pdoc_command_list(output_directory: Path, module: str) -> List[str]:
-    return [
-        "pdoc",
-        "--html",
-        f"{module}",
-        "--output-dir",
-        f"{str(output_directory)}",
-        "--force",
-        "--config",
-        "show_type_annotations=True",
-    ]
-
-
 def generate_documentation(output_directory: Path, module_to_document: str) -> None:
-    """Ensures the documentation is in the correct location.
-
-    Pdoc nests its docs output in a folder with the module's name.
-    This process removes this unwanted folder.
-    """
+    """Generates the documentation."""
     _clear_previous_docs(output_directory)
     os.makedirs(str(output_directory), exist_ok=True)
-    with TemporaryDirectory() as temp_dir:
-        _call_pdoc(temp_dir, module_to_document)
-        docs_contents_dir = temp_dir.joinpath(module_to_document)
-        if docs_contents_dir.exists() and docs_contents_dir.is_dir():
-            for element in docs_contents_dir.iterdir():
-                shutil.move(str(element), str(output_directory))
-
-
-def _call_pdoc(output_directory: Path, module: str) -> None:
-    """Calls Pdoc for generating the docs."""
-    logger.info("Creating Pdoc documentation.")
-    command_list = _generate_pdoc_command_list(output_directory, module)
-    check_call(command_list)
+    get_language_specifics().generate_code_documentation(output_directory, module_to_document)
 
 
 def generate_docs(output_directory: Path, module: str) -> int:

continuous_delivery_scripts/language_specifics.py

@@ -0,0 +1,53 @@
+"""Language plugins Loader."""
+
+import logging
+from typing import Optional, Dict, cast
+
+from continuous_delivery_scripts.utils.configuration import configuration, ConfigurationVariable
+from continuous_delivery_scripts.utils.language_specifics_base import BaseLanguage
+
+# this import is needed for plugin subclass detection
+from continuous_delivery_scripts.plugins import *  # noqa
+
+logger = logging.getLogger(__name__)
+
+
+def _all_language_plugins() -> Dict[str, BaseLanguage]:
+    """Get all language plugins which inherit from BaseLanguage (with the exception of other base class).
+
+    :return: A list of classes containing language plugins
+    """
+    all_plugins = BaseLanguage.__subclasses__()
+    return {
+        la.get_related_language().lower().strip(): la
+        for la in [lang() for lang in all_plugins if lang != BaseLanguage]  # type: ignore
+    }
+
+
+def _sanitise_program_language() -> str:
+    return str(configuration.get_value(ConfigurationVariable.PROGRAMMING_LANGUAGE)).lower().strip()
+
+
+def _fetch_project_language_specifics() -> BaseLanguage:
+    return cast(BaseLanguage, _all_language_plugins().get(_sanitise_program_language()))
+
+
+class PluginLoader:
+    """Plugin loader."""
+
+    _instance: Optional[BaseLanguage] = None
+
+    def __init__(self) -> None:
+        """Initialiser."""
+        if not PluginLoader._instance:
+            PluginLoader._instance = _fetch_project_language_specifics()
+
+    @property
+    def languageSpecifics(self) -> BaseLanguage:
+        """Gets project language specifics."""
+        return cast(BaseLanguage, PluginLoader._instance)
+
+
+def get_language_specifics() -> BaseLanguage:
+    """Gets the language specific actions."""
+    return PluginLoader().languageSpecifics

continuous_delivery_scripts/license_files.py

@@ -15,15 +15,12 @@
 from datetime import datetime
 from continuous_delivery_scripts.utils.configuration import configuration, ConfigurationVariable
 from continuous_delivery_scripts.utils.logging import set_log_level, log_exception
-from continuous_delivery_scripts.utils.python_helpers import flatten_dictionary
+from continuous_delivery_scripts.utils.python.python_helpers import flatten_dictionary
+from continuous_delivery_scripts.language_specifics import get_language_specifics
 from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
-LICENCE_HEADER_TEMPLATE = """Copyright (C) {date} {author}. All rights reserved.
-SPDX-License-Identifier: {licence_identifier}
-"""
-
 FILES_TO_IGNORE = ["*.yml", "*.yaml"]
 
 
@@ -34,7 +31,9 @@ def add_licence_header(verbose_count: int) -> None:
     """
     # copyright (https://github.com/knipknap/copyright) was first considered but
     # comprises quite a few bugs and does not seem active anymore.
-    template_string = _generate_header_template()
+    if not get_language_specifics().can_add_licence_headers():
+        return
+    template_string = get_language_specifics().generate_source_licence_header_template()
     with tempfile.NamedTemporaryFile(suffix=".tmpl", delete=False) as template_file:
         template_file_path = Path(template_file.name)
         logger.debug(f"Creates template file in {str(template_file_path)}")
@@ -44,15 +43,6 @@ def add_licence_header(verbose_count: int) -> None:
         _call_licensehearders(copyright_config, verbose_count)
 
 
-def _generate_header_template() -> str:
-    """Generates the header template which is put at the top of source files."""
-    return LICENCE_HEADER_TEMPLATE.format(
-        licence_identifier=configuration.get_value(ConfigurationVariable.FILE_LICENCE_IDENTIFIER),
-        author="${owner}",
-        date="${years}",
-    )
-
-
 def _call_licensehearders(config: dict, verbose_count: int) -> None:
     """Runs licenseheaders tool."""
     args = ["licenseheaders"]
@@ -83,7 +73,7 @@ def get_tool_config(template_file: Path) -> dict:
         "projname": configuration.get_value(ConfigurationVariable.PROJECT_NAME),
         "tmpl": str(template_file),
         "years": copyright_dates,
-        "additional-extensions": "python=.toml",
+        "additional-extensions": "python=.toml c=.go",
         "exclude": FILES_TO_IGNORE,
     }
 

continuous_delivery_scripts/plugins/__init__.py

@@ -0,0 +1,9 @@
+"""Language specific actions."""
+import glob
+import os
+
+all_plugin_files = [
+    os.path.splitext(os.path.basename(filename))[0]
+    for filename in glob.glob(os.path.join(os.path.dirname(__file__), "*.py"))
+]
+__all__ = all_plugin_files

continuous_delivery_scripts/plugins/golang.py

@@ -0,0 +1,46 @@
+"""Plugin for Golang projects."""
+import logging
+from pathlib import Path
+from typing import Optional
+from continuous_delivery_scripts.utils.language_specifics_base import BaseLanguage, get_language_from_file_name
+from continuous_delivery_scripts.spdx_report.spdx_project import SpdxProject
+
+logger = logging.getLogger(__name__)
+
+
+class Go(BaseLanguage):
+    """Specific actions for a Golang project."""
+
+    def get_related_language(self) -> str:
+        """Gets the related language."""
+        return get_language_from_file_name(__file__)
+
+    def package_software(self) -> None:
+        """No operation."""
+        super().package_software()
+
+    def release_package_to_repository(self) -> None:
+        """No operation."""
+        super().release_package_to_repository()
+
+    def check_credentials(self) -> None:
+        """Checks any credentials."""
+        super().check_credentials()
+
+    def generate_code_documentation(self, output_directory: Path, module_to_document: str) -> None:
+        """Generates the code documentation."""
+        super().generate_code_documentation(output_directory, module_to_document)
+        # TODO
+
+    def can_add_licence_headers(self) -> bool:
+        """States that licence headers can be added."""
+        return True
+
+    def can_get_project_metadata(self) -> bool:
+        """States whether project metadata can be retrieved."""
+        return False
+
+    def get_current_spdx_project(self) -> Optional[SpdxProject]:
+        """Gets current SPDX description."""
+        # TODO
+        return None

continuous_delivery_scripts/plugins/noop.py

@@ -0,0 +1,46 @@
+"""No Operation plugin."""
+import logging
+from pathlib import Path
+
+from continuous_delivery_scripts.spdx_report.spdx_project import SpdxProject
+from continuous_delivery_scripts.utils.language_specifics_base import BaseLanguage, get_language_from_file_name
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class NoOp(BaseLanguage):
+    """Specific actions for a NoOp project."""
+
+    def get_related_language(self) -> str:
+        """Gets the related language."""
+        return get_language_from_file_name(__file__)
+
+    def package_software(self) -> None:
+        """No Op."""
+        super().package_software()
+
+    def release_package_to_repository(self) -> None:
+        """No Op."""
+        super().release_package_to_repository()
+
+    def check_credentials(self) -> None:
+        """No Op."""
+        super().check_credentials()
+
+    def generate_code_documentation(self, output_directory: Path, module_to_document: str) -> None:
+        """No Op."""
+        super().generate_code_documentation(output_directory, module_to_document)
+
+    def can_add_licence_headers(self) -> bool:
+        """No Op."""
+        return False
+
+    def can_get_project_metadata(self) -> bool:
+        """No Op."""
+        """States whether project metadata can be retrieved."""
+        return False
+
+    def get_current_spdx_project(self) -> Optional[SpdxProject]:
+        """No Op."""
+        return None