Merge pull request #38 from timvink/12-pdf-compat

Release 0.7

Author: timvink

README.md

@@ -68,6 +68,8 @@ When writing your own [custom themes](https://www.mkdocs.org/user-guide/custom-t
 {% endif %}
 ```
 
+You can style the output using CSS: the date outputs are always wrapped in `<span class='git-revision-date-localized-plugin git-revision-date-localized-plugin-{type}></span>` (where `{type}` is replaced with the `type` option set in the plugin).
+
 ## Options
 
 You can customize the plugin by setting options in `mkdocs.yml`. For example:
@@ -86,7 +88,7 @@ plugins:
 Default is `date`. To change the date format, set the `type` parameter to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `timeago`. Example outputs:
 
 ```bash
-28 November, 2019           # type: date
+28 November, 2019           # type: date (default)
 28 November, 2019 13:57:28  # type: datetime
 2019-11-28                  # type: iso_date
 2019-11-28 13:57:26         # type: iso_datetime

mkdocs_git_revision_date_localized_plugin/ci.py

@@ -0,0 +1,101 @@
+import os
+import logging
+
+
+def raise_ci_warnings(repo):
+    """
+    raise warnings when users use mkdocs-git-revision-date-localized-plugin
+    on CI build runners
+
+    Args:
+        repo (GitPython.git.repo): The Git repo object
+    """
+
+    if not is_shallow_clone(repo):
+        return None
+
+    n_commits = commit_count(repo)
+
+    # Gitlab Runners
+    if os.environ.get("GITLAB_CI") and n_commits < 50:
+        # Default is GIT_DEPTH of 50 for gitlab
+        logging.warning(
+            """
+                [git-revision-date-localized-plugin] Running on a gitlab runner might lead to wrong git revision dates
+                due to a shallow git fetch depth.
+                Make sure to set GIT_DEPTH to 1000 in your .gitlab-ci.yml file.
+                (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
+                """
+        )
+
+    # Github Actions
+    if os.environ.get("GITHUB_ACTIONS") and n_commits == 1:
+        # Default is fetch-depth of 1 for github actions
+        logging.warning(
+            """
+                [git-revision-date-localized-plugin] Running on github actions might lead to wrong git revision dates
+                due to a shallow git fetch depth.
+                Try setting fetch-depth to 0 in your github action
+                (see https://github.com/actions/checkout).
+                """
+        )
+
+    # Bitbucket pipelines
+    if os.environ.get("CI") and n_commits < 50:
+        # Default is fetch-depth of 50 for bitbucket pipelines
+        logging.warning(
+            """
+                [git-revision-date-localized-plugin] Running on bitbucket pipelines might lead to wrong git revision dates
+                due to a shallow git fetch depth.
+                Try setting "clone: depth" to "full" in your pipeline
+                (see https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/
+                and search 'depth').
+                """
+        )
+
+    # Azure Devops Pipeline
+    # Does not limit fetch-depth by default
+    if os.environ.get("Agent.Source.Git.ShallowFetchDepth", 10e99) < n_commits:
+        logging.warning(
+            """
+                [git-revision-date-localized-plugin] Running on Azure pipelines with limited fetch-depth might lead to wrong git revision dates
+                due to a shallow git fetch depth.
+                Remove any Shallow Fetch settings
+                (see https://docs.microsoft.com/en-us/azure/devops/pipelines/repos/pipeline-options-for-git?view=azure-devops#shallow-fetch).
+                """
+        )
+
+
+def commit_count(repo) -> bool:
+    """
+    Helper function to determine the number of commits in a repository
+
+    Args:
+        repo (GitPython.Repo.git): Repository
+
+    Returns:
+        count (int): Number of commits
+    """
+    refs = repo.for_each_ref().split("\n")
+    refs = [x.split()[0] for x in refs]
+
+    counts = [int(repo.rev_list(x, count=True, first_parent=True)) for x in refs]
+    return max(counts)
+
+
+def is_shallow_clone(repo) -> bool:
+    """
+    Helper function to determine if repository
+    is a shallow clone.
+
+    References & Context:
+    https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues/10
+    https://stackoverflow.com/a/37203240/5525118
+
+    Args:
+        repo (GitPython.Repo.git): Repository
+
+    Returns:
+        bool: If a repo is shallow clone
+    """
+    return os.path.exists(".git/shallow")

mkdocs_git_revision_date_localized_plugin/plugin.py

@@ -112,6 +112,7 @@ def on_post_page(self, output_content: str, **kwargs) -> str:
         if self.config.get("type") != "timeago":
             return output_content
 
+        # Insert timeago.js dependencies
         extra_js = """
           <script src="https://cdnjs.cloudflare.com/ajax/libs/timeago.js/4.0.0-beta.2/timeago.min.js"></script>
           <script src="https://cdnjs.cloudflare.com/ajax/libs/timeago.js/4.0.0-beta.2/timeago.locales.min.js"></script>
@@ -122,7 +123,23 @@ def on_post_page(self, output_content: str, **kwargs) -> str:
           </script>
         """
         idx = output_content.index("</body>")
-        return output_content[:idx] + extra_js + output_content[idx:]
+        output_content = output_content[:idx] + extra_js + output_content[idx:]
+
+        # timeago output is dynamic, which breaks when you print a page
+        # This ensures fallback to type "iso_date"
+        extra_css = """
+        <style>
+        .git-revision-date-localized-plugin-iso_date { display: none }
+        @media print {
+           .git-revision-date-localized-plugin-iso_date { display: inline } 
+           .git-revision-date-localized-plugin-timeago { display: none } 
+        }
+        </style>
+        """
+        idx = output_content.index("</head>")
+        output_content = output_content[:idx] + extra_css + output_content[idx:]
+
+        return output_content
 
     def on_page_markdown(
         self, markdown: str, page: Page, config: config_options.Config, files, **kwargs
@@ -154,6 +171,13 @@ def on_page_markdown(
             fallback_to_build_date=self.config.get("fallback_to_build_date"),
         )
         revision_date = revision_dates[self.config["type"]]
+
+        # timeago output is dynamic, which breaks when you print a page
+        # This ensures fallback to type "iso_date"
+        # controlled via CSS (see on_post_page() event)
+        if self.config["type"] == "timeago":
+            revision_date += revision_dates["iso_date"]
+
         page.meta["git_revision_date_localized"] = revision_date
         return re.sub(
             r"\{\{\s*[page\.meta\.]*git_revision_date_localized\s*\}\}",

mkdocs_git_revision_date_localized_plugin/util.py

@@ -1,12 +1,13 @@
 # standard library
 import logging
-import os
 import time
 from datetime import datetime
 
+from mkdocs_git_revision_date_localized_plugin.ci import raise_ci_warnings
+
 # 3rd party
 from babel.dates import format_date, get_timezone
-from git import Repo, Git, GitCommandError, GitCommandNotFound
+from git import Repo, GitCommandError, GitCommandNotFound
 
 
 class Util:
@@ -33,32 +34,8 @@ def __init__(self, path: str = ".", config={}):
                 raise
 
         # Checks if user is running builds on CI
-        # See https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues/10
-        if is_shallow_clone(self.repo):
-            n_commits = commit_count(self.repo)
-
-            if os.environ.get("GITLAB_CI") and n_commits < 50:
-                # Default is GIT_DEPTH of 50 for gitlab
-                logging.warning(
-                    """
-                       Running on a gitlab runner might lead to wrong git revision dates
-                       due to a shallow git fetch depth.
-                       Make sure to set GIT_DEPTH to 1000 in your .gitlab-ci.yml file.
-                       (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
-                       """
-                )
-            if os.environ.get("GITHUB_ACTIONS") and n_commits == 1:
-                # Default is fetch-depth of 1 for github actions
-                logging.warning(
-                    """
-                       Running on github actions might lead to wrong git revision dates
-                       due to a shallow git fetch depth.
-                       Try setting fetch-depth to 0 in your github action
-                       (see https://github.com/actions/checkout).
-                       """
-                )
-
-            # TODO add bitbucket
+        # and raise appropriate warnings
+        raise_ci_warnings(self.repo)
 
     @staticmethod
     def _date_formats(
@@ -87,7 +64,7 @@ def _date_formats(
             + loc_revision_date.strftime("%H:%M:%S"),
             "iso_date": loc_revision_date.strftime("%Y-%m-%d"),
             "iso_datetime": loc_revision_date.strftime("%Y-%m-%d %H:%M:%S"),
-            "timeago": "<span class='timeago' datetime='%s' locale='%s'></span>"
+            "timeago": '<span class="timeago" datetime="%s" locale="%s"></span>'
             % (loc_revision_date.isoformat(), locale),
         }
 
@@ -155,41 +132,15 @@ def get_revision_date_for_file(
                     % path
                 )
 
-        return self._date_formats(
+        date_formats = self._date_formats(
             unix_timestamp=unix_timestamp, time_zone=time_zone, locale=locale
         )
 
+        # Wrap in <span> for styling
+        for date_type, date_string in date_formats.items():
+            date_formats[date_type] = (
+                '<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-%s">%s</span>'
+                % (date_type, date_string)
+            )
 
-def is_shallow_clone(repo: Git) -> bool:
-    """
-    Helper function to determine if repository
-    is a shallow clone.
-
-    References:
-    https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues/10
-    https://stackoverflow.com/a/37203240/5525118
-
-    Args:
-        repo (git.Repo): Repository
-
-    Returns:
-        bool: If a repo is shallow clone
-    """
-    return os.path.exists(".git/shallow")
-
-
-def commit_count(repo: Git) -> bool:
-    """
-    Helper function to determine the number of commits in a repository
-
-    Args:
-        repo (git.Repo): Repository
-
-    Returns:
-        count (int): Number of commits
-    """
-    refs = repo.for_each_ref().split("\n")
-    refs = [x.split()[0] for x in refs]
-
-    counts = [int(repo.rev_list(x, count=True, first_parent=True)) for x in refs]
-    return max(counts)
+        return date_formats

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="mkdocs-git-revision-date-localized-plugin",
-    version="0.6",
+    version="0.7",
     description="Mkdocs plugin that enables displaying the localized date of the last git modification of a markdown file.",
     long_description=long_description,
     long_description_content_type="text/markdown",

tests/test_builds.py

@@ -200,7 +200,7 @@ def validate_build(testproject_path, plugin_config: dict = {}):
         fallback_to_build_date=plugin_config.get("fallback_to_build_date"),
     )
 
-    searches = [re.search(x, contents) for x in date_formats.values()]
+    searches = [x in contents for x in date_formats.values()]
     assert any(searches), "No correct date formats output was found"
 
 
@@ -240,7 +240,7 @@ def test_date_formats():
         "datetime": "February 22, 2020 18:52:09",
         "iso_date": "2020-02-22",
         "iso_datetime": "2020-02-22 18:52:09",
-        "timeago": "<span class='timeago' datetime='2020-02-22T18:52:09+00:00' locale='en'></span>",
+        "timeago": '<span class="timeago" datetime="2020-02-22T18:52:09+00:00" locale="en"></span>',
     }
 
 
@@ -301,7 +301,7 @@ def test_build_material_theme(tmp_path):
     # in German because locale is set to 'de'
     index_file = testproject_path / "site/index.html"
     contents = index_file.read_text(encoding="utf8")
-    assert re.search(r"Letztes Update\:\s[\w].+", contents)
+    assert re.search(r"Letztes Update\:\s[<span class].+", contents)
 
 
 def test_material_theme_locale(tmp_path):
@@ -318,7 +318,7 @@ def test_material_theme_locale(tmp_path):
     # The date will be in german though
     index_file = testproject_path / "site/index.html"
     contents = index_file.read_text(encoding="utf8")
-    assert re.search(r"Last update\:\s[\w].+", contents)
+    assert re.search(r"Last update\:\s[<span class].+", contents)
 
 
 def test_material_theme_no_locale(tmp_path):
@@ -334,7 +334,7 @@ def test_material_theme_no_locale(tmp_path):
     # in German because locale is set to 'de'
     index_file = testproject_path / "site/index.html"
     contents = index_file.read_text(encoding="utf8")
-    assert re.search(r"Last update\:\s[\w].+", contents)
+    assert re.search(r"Last update\:\s[<span class].+", contents)
 
 
 def test_type_timeago(tmp_path):