Throw usefull error messages when using CI runners, see #10

Author: timvink

README.md

@@ -30,6 +30,13 @@ plugins:
 
 > If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set.
 
+### When using CI runners
+
+The plugin needs access to the last commit that touched a file to be able to retrieve the date. If you build your docs using CI then you might need to change the default settings: 
+
+- github actions: set `fetch_depth` to `0` ([docs](https://github.com/actions/checkout))
+- gitlab runners: set `GIT_DEPTH` to `1000` ([docs](https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone))
+
 ## Usage
 
 ### In supported themes

mkdocs_git_revision_date_localized_plugin/util.py

@@ -1,3 +1,5 @@
+import os
+import logging
 from git import Git
 from datetime import datetime
 from babel.dates import format_date
@@ -7,24 +9,20 @@ class Util:
     def __init__(self):
         self.g = Git()
 
-    def get_revision_date_for_file(self, path: str, locale: str = 'en'):
+    @staticmethod
+    def _date_formats(unix_timestamp, locale = 'en'):
         """
-        Determine localized date variants for a given file
+        Returns different date formats / types.
         
         Args:
-            path (str): Location of a file that is part of a GIT repository
-            locale (str, optional): Locale code of language to use. Defaults to 'en'.
-        
+            unix_timestamp (datetiment): a timestamp in seconds since 1970
+            locale (str): Locale code of language to use. Defaults to 'en'.
+            
         Returns:
-            dict: localized date variants 
+            dict: different date formats
         """
 
-        unix_timestamp = self.g.log(path, n=1, date='short', format='%at')
-        
-        if not unix_timestamp:
-            unix_timestamp = datetime.utcnow().timestamp() 
-            print('WARNING - %s has no git logs, using current timestamp' % path)
-        
+        # Convert to millisecond timestamp
         unix_timestamp = int(unix_timestamp)
         timestamp_in_ms = unix_timestamp * 1000
 
@@ -37,3 +35,42 @@ def get_revision_date_for_file(self, path: str, locale: str = 'en'):
             'iso_datetime' : revision_date.strftime("%Y-%m-%d %H:%M:%S"), 
             'timeago' : "<span class='timeago' datetime='%s' locale='%s'></span>" % (timestamp_in_ms, locale)
         }
+        
+
+    def get_revision_date_for_file(self, path, locale = 'en'):
+        """
+        Determine localized date variants for a given file
+        
+        Args:
+            path (str): Location of a file that is part of a GIT repository
+            locale (str, optional): Locale code of language to use. Defaults to 'en'.
+        
+        Returns:
+            dict: localized date variants 
+        """
+        
+        unix_timestamp = self.g.log(path, n=1, date='short', format='%at')
+        
+
+        if not unix_timestamp:
+            
+            if os.environ.get('GITLAB_CI'):
+                raise EnvironmentError("""Cannot access git commit for '%s'. 
+                       Try setting GIT_DEPTH to 1000 in your .gitlab-ci.yml file.
+                       (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
+                       Or disable mkdocs-git-revision-date-localized-plugin when using gitlab runners.
+                       """ % path)
+
+            if os.environ.get('GITHUB_ACTIONS'):
+                raise EnvironmentError("""Cannot access git commit for '%s'. 
+                       Try setting fetch-depth to 1 in your github action
+                       (see https://github.com/actions/checkout).
+                       Or disable mkdocs-git-revision-date-localized-plugin when using github actions.
+                       """ % path)
+
+            unix_timestamp = datetime.utcnow().timestamp()
+            logging.warning('%s has no git logs, using current timestamp' % path)
+            
+
+        
+        return self._date_formats(unix_timestamp)