Add option to enable/disable git use. (#187)

Guts · web-flow · commit a31393adf1ef · 2023-07-24T19:04:40.000+02:00
Add option `use_git`, defaults to True. If not, the plugin does not try use the git log nor does not check if this is a valid git repository and use only informations from page meta (YAML frontmatter). Closes #160
diff --git a/.github/workflows/lint-and-tests.yml b/.github/workflows/lint-and-tests.yml
@@ -40,7 +40,6 @@ jobs:
           python -m pip install --upgrade pip setuptools wheel
           python -m pip install --upgrade -r requirements.txt
           python -m pip install --upgrade -r requirements/development.txt
-          python -m pip install --upgrade -r requirements/documentation.txt
 
       - name: Lint with flake8
         run: |
@@ -53,7 +52,7 @@ jobs:
         run: python -m pip install -e .
 
       - name: Run Unit tests
-        run: pytest
+        run: python -m pytest
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3.1.4
diff --git a/mkdocs_rss_plugin/plugin.py b/mkdocs_rss_plugin/plugin.py
@@ -58,12 +58,11 @@ class GitRssPlugin(BasePlugin):
         ("match_path", config_options.Type(str, default=".*")),
         ("pretty_print", config_options.Type(bool, default=False)),
         ("url_parameters", config_options.Type(dict, default=None)),
+        ("use_git", config_options.Type(bool, default=True)),
     )
 
     def __init__(self):
         """Instanciation."""
-        # tooling
-        self.util = Util()
         # dates source
         self.src_date_created = self.src_date_updated = "git"
         self.meta_datetime_format = None
@@ -94,6 +93,9 @@ def on_config(self, config: config_options.Config) -> dict:
         if not self.config.get("enabled"):
             return config
 
+        # instanciate plugin tooling
+        self.util = Util(use_git=self.config.get("use_git", True))
+
         # check template dirs
         if not Path(DEFAULT_TEMPLATE_FILENAME).is_file():
             raise FileExistsError(DEFAULT_TEMPLATE_FILENAME)
@@ -152,10 +154,17 @@ def on_config(self, config: config_options.Config) -> dict:
                         f"format %H:%M. Trace: {err}"
                     )
 
-            logger.debug(
-                "[rss-plugin] Dates will be retrieved from page meta (yaml "
-                "frontmatter). The git log will be used as fallback."
-            )
+            if self.config.get("use_git", True):
+                logger.debug(
+                    "[rss-plugin] Dates will be retrieved FIRSTLY from page meta (yaml "
+                    "frontmatter). The git log will be used as fallback."
+                )
+            else:
+                logger.debug(
+                    "[rss-plugin] Dates will be retrieved ONLY from page meta (yaml "
+                    "frontmatter). The build date will be used as fallback, without any "
+                    "call to Git."
+                )
         else:
             logger.debug("[rss-plugin] Dates will be retrieved from git log.")
 
diff --git a/mkdocs_rss_plugin/util.py b/mkdocs_rss_plugin/util.py
@@ -52,26 +52,53 @@
 
 
 class Util:
-    def __init__(self, path: str = "."):
+    """Plugin logic."""
+
+    git_is_valid: bool = False
+
+    def __init__(self, path: str = ".", use_git: bool = True):
         """Class hosting the plugin logic.
 
         :param str path: path tot the git repository to use. Defaults to: "." - optional
+        :param bool use_git: flag to use git under the hood or not, defaults to True
         """
-        try:
-            git_repo = Repo(path, search_parent_directories=True)
-            self.repo = git_repo.git
-            self.git_is_valid = 1
-        except InvalidGitRepositoryError as err:
-            logging.warning(
-                f"[rss-plugin] Path '{path}' is not a valid git directory. Trace: {err}"
+        if use_git:
+            logger.debug("[rss-plugin] Git use is disabled.")
+            try:
+                git_repo = Repo(path, search_parent_directories=True)
+                self.repo = git_repo.git
+                self.git_is_valid = True
+            except InvalidGitRepositoryError as err:
+                logger.warning(
+                    f"[rss-plugin] Path '{path}' is not a valid git directory. "
+                    "Only page.meta (YAML frontmatter will be used). "
+                    "To disable this warning, set 'use_git: false' in plugin options. "
+                    f"Trace: {err}"
+                )
+                self.git_is_valid = False
+                use_git = False
+            except Exception as err:
+                logger.warning(
+                    f"[rss-plugin] Unrecognized git issue. "
+                    "Only page.meta (YAML frontmatter will be used). "
+                    "To disable this warning, set 'use_git: false' in plugin options. "
+                    f"Trace: {err}"
+                )
+                self.git_is_valid = False
+                use_git = False
+
+            # Checks if user is running builds on CI and raise appropriate warnings
+            if self.git_is_valid:
+                CiHandler(git_repo.git).raise_ci_warnings()
+        else:
+            self.git_is_valid = False
+            logger.debug(
+                "[rss-plugin] Git use is disabled. "
+                "Only page.meta (YAML frontmatter will be used). "
             )
-            self.git_is_valid = 0
-        except Exception as err:
-            logging.warning(f"[rss-plugin] Git issue: {err}")
-            self.git_is_valid = 0
 
-        # Checks if user is running builds on CI and raise appropriate warnings
-        CiHandler(git_repo.git).raise_ci_warnings()
+        # save git enable/disable status
+        self.use_git = use_git
 
     def build_url(self, base_url: str, path: str, args_dict: dict = None) -> str:
         """Build URL using base URL, cumulating existing and passed path, \
@@ -135,27 +162,48 @@ def get_file_dates(
         dt_created = dt_updated = None
 
         # if enabled, try to retrieve dates from page metadata
-        if source_date_creation != "git" and in_page.meta.get(source_date_creation):
+        if not self.use_git or (
+            source_date_creation != "git" and in_page.meta.get(source_date_creation)
+        ):
             dt_created = self.get_date_from_meta(
                 date_metatag_value=in_page.meta.get(source_date_creation),
                 meta_datetime_format=meta_datetime_format,
                 meta_datetime_timezone=meta_default_timezone,
                 meta_default_time=meta_default_time,
             )
             if isinstance(dt_created, str):
-                logger.error(f"Creation date is a string: {dt_created}")
-                dt_created = None
+                logger.info(
+                    f"[rss-plugin] Creation date of {in_page.file.abs_src_path} is an "
+                    f"a character string: {dt_created} ({type(dt_created)})"
+                )
+
+            elif dt_created is None:
+                logger.info(
+                    f"[rss-plugin] Creation date of {in_page.file.abs_src_path} has not "
+                    "been recognized."
+                )
 
-        if source_date_update != "git" and in_page.meta.get(source_date_update):
+        if not self.use_git or (
+            source_date_update != "git" and in_page.meta.get(source_date_update)
+        ):
             dt_updated = self.get_date_from_meta(
                 date_metatag_value=in_page.meta.get(source_date_update),
                 meta_datetime_format=meta_datetime_format,
                 meta_datetime_timezone=meta_default_timezone,
                 meta_default_time=meta_default_time,
             )
+
             if isinstance(dt_updated, str):
-                logger.error(f"Update date is a string: {dt_updated}")
-                dt_updated = None
+                logger.info(
+                    f"[rss-plugin] Update date of {in_page.file.abs_src_path} is an "
+                    f"a character string: {dt_updated} ({type(dt_updated)})"
+                )
+
+            elif dt_updated is None:
+                logger.info(
+                    f"[rss-plugin] Update date of {in_page.file.abs_src_path} is an "
+                    f"unrecognized type: {dt_updated} ({type(dt_updated)})"
+                )
 
         # explore git log
         if self.git_is_valid:
@@ -180,12 +228,14 @@ def get_file_dates(
                 logging.warning(
                     f"[rss-plugin] Unable to read git logs of '{in_page.file.abs_src_path}'. "
                     "Is git log readable? Falling back to build date. "
+                    "To disable this warning, set 'use_git: false' in plugin options. "
                     f"Trace: {err}"
                 )
             except GitCommandNotFound as err:
                 logging.error(
                     "[rss-plugin] Unable to perform command 'git log'. Is git installed? "
-                    " Falling back to build date. "
+                    "Falling back to build date. "
+                    "To disable this warning, set 'use_git: false' in plugin options. "
                     f"Trace: {err}"
                 )
                 self.git_is_valid = 0
@@ -334,11 +384,22 @@ def get_date_from_meta(
                     time_to_add = datetime.min.time()
                 out_date = datetime.combine(date_metatag_value, time_to_add)
             else:
-                return "[rss-plugin] Incompatible date type."
+                logger.debug(
+                    f"[rss-plugin] Incompatible date type: {type(date_metatag_value)}"
+                )
+                return out_date
         except ValueError as err:
-            return f"[rss-plugin] Incompatible date found. Trace: {err}"
+            logger.error(
+                f"[rss-plugin] Incompatible date found: {date_metatag_value=} "
+                f"{type(date_metatag_value)}. Trace: {err}"
+            )
+            return out_date
         except Exception as err:
-            return f"[rss-plugin] Unable to retrieve creation date. Trace: {err}"
+            logger.error(
+                f"[rss-plugin] Unable to retrieve creation date: {date_metatag_value=} "
+                f"{type(date_metatag_value)}. Trace: {err}"
+            )
+            return out_date
 
         if not out_date.tzinfo:
             out_date = set_datetime_zoneinfo(out_date, meta_datetime_timezone)
diff --git a/tests/fixtures/mkdocs_complete_no_git.yml b/tests/fixtures/mkdocs_complete_no_git.yml
@@ -0,0 +1,43 @@
+# Project information
+site_name: MkDocs RSS Plugin - TEST
+site_description: Basic setup to test against MkDocs RSS plugin
+site_author: Julien Moura (Guts)
+site_url: https://guts.github.io/mkdocs-rss-plugin
+copyright: "Guts - In Geo Veritas"
+
+# Repository
+repo_name: "guts/mkdocs-rss-plugin"
+repo_url: "https://github.com/guts/mkdocs-rss-plugin"
+
+use_directory_urls: true
+
+plugins:
+  - rss:
+      abstract_chars_count: 160 # -1 for full content
+      categories:
+        - tags
+      comments_path: "#__comments"
+      date_from_meta:
+        as_creation: "date"
+        as_update: false
+        datetime_format: "%Y-%m-%d %H:%M"
+        default_timezone: Europe/Paris
+        default_time: "09:30"
+      enabled: true
+      feed_ttl: 1440
+      image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png
+      length: 20
+      pretty_print: false
+      match_path: ".*"
+      url_parameters:
+        utm_source: "documentation"
+        utm_medium: "RSS"
+        utm_campaign: "feed-syndication"
+      use_git: false
+theme:
+  name: readthedocs
+  locale: fr
+
+# Extensions to enhance markdown
+markdown_extensions:
+  - meta
diff --git a/tests/test_build_no_git.py b/tests/test_build_no_git.py
@@ -0,0 +1,120 @@
+#! python3  # noqa E265
+
+"""Usage from the repo root folder:
+
+    .. code-block:: python
+
+        # for whole test
+        python -m unittest tests.test_build_no_git
+        # for specific test
+        python -m unittest tests.test_build_no_git.TestBuildRssNoGit.test_not_git_repo_without_option
+"""
+
+# #############################################################################
+# ########## Libraries #############
+# ##################################
+
+# Standard library
+import tempfile
+import unittest
+
+# logging
+from logging import DEBUG, getLogger
+from pathlib import Path
+from traceback import format_exception
+
+# test suite
+from tests.base import BaseTest
+
+logger = getLogger(__name__)
+logger.setLevel(DEBUG)
+
+# #############################################################################
+# ########## Classes ###############
+# ##################################
+
+
+class TestBuildRssNoGit(BaseTest):
+    """Test MkDocs build with RSS plugin but without git."""
+
+    # -- Standard methods --------------------------------------------------------
+    @classmethod
+    def setUpClass(cls):
+        """Executed when module is loaded before any test."""
+        pass
+
+    def setUp(self):
+        """Executed before each test."""
+        pass
+
+    def tearDown(self):
+        """Executed after each test."""
+        pass
+
+    @classmethod
+    def tearDownClass(cls):
+        """Executed after the last test."""
+        # # In case of some tests failure, ensure that everything is cleaned up
+        # temp_page = Path("tests/fixtures/docs/temp_page_not_in_git_log.md")
+        # # if temp_page.exists():
+        # #     temp_page.unlink()
+
+        git_dir = Path("_git")
+        if git_dir.exists():
+            git_dir.replace(git_dir.with_name(".git"))
+
+    # -- TESTS ---------------------------------------------------------
+    def test_not_git_repo(self):
+        # temporarily rename the git folder to fake a non-git repo
+        git_dir = Path(".git")
+        git_dir_tmp = git_dir.with_name("_git")
+        git_dir.replace(git_dir_tmp)
+
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            cli_result = self.build_docs_setup(
+                testproject_path="docs",
+                mkdocs_yml_filepath=Path("tests/fixtures/mkdocs_complete_no_git.yml"),
+                output_path=tmpdirname,
+                strict=True,
+            )
+
+            self.assertIsNone(cli_result.exception)
+            self.assertEqual(cli_result.exit_code, 0, cli_result)
+
+        # restore name
+        git_dir_tmp.replace(git_dir)
+
+    def test_not_git_repo_without_option(self):
+        # temporarily rename the git folder to fake a non-git repo
+        git_dir = Path(".git")
+        git_dir_tmp = git_dir.with_name("_git")
+        git_dir.replace(git_dir_tmp)
+
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            cli_result = self.build_docs_setup(
+                testproject_path="docs",
+                mkdocs_yml_filepath=Path("tests/fixtures/mkdocs_complete.yml"),
+                output_path=tmpdirname,
+                strict=True,
+            )
+
+            self.assertIsNotNone(cli_result.exception)
+            self.assertEqual(
+                cli_result.exit_code,
+                1,
+                format_exception(
+                    type(cli_result.exception),
+                    cli_result.exception,
+                    cli_result.exception.__traceback__,
+                ),
+            )
+
+        # restore name
+        git_dir_tmp.replace(git_dir)
+
+
+# ##############################################################################
+# ##### Stand alone program ########
+# ##################################
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_config.py b/tests/test_config.py
