Merge branch 'master' of github.com:timvink/mkdocs-git-revision-date-localized-plugin

Author: timvink

README.md

@@ -120,6 +120,7 @@ plugins:
       timezone: Europe/Amsterdam
       locale: en
       fallback_to_build_date: false
+      enable_creation_date: true
       exclude:
           - index.md
 ```
@@ -152,6 +153,10 @@ Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/L
 
 Default is `false`. If set to `true` the plugin will use the time at `mkdocs build` instead of the file's last git revision date *when git is not available*. This means the revision date will be incorrect, but this can be acceptable if you want your project to also successfully build in environments with no access to GIT.
 
+### `enable_creation_date`
+
+Default is `false`. If set to `true`, you will be able to use `{{git_creation_date_localized}}` in markdown files and `page.meta.git_creation_date_localized` in page templates.
+
 ### `exclude`
 
 Default is empty. Specify a list of page source paths (one per line) that should not have a revision date included (excluded from processing by this plugin). This can be useful for example to remove the revision date from the front page. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude:` with `- subfolder/page.md`. Some examples:

mkdocs_git_revision_date_localized_plugin/plugin.py

@@ -37,6 +37,7 @@ class GitRevisionDateLocalizedPlugin(BasePlugin):
         ("type", config_options.Type(str, default="date")),
         ("timezone", config_options.Type(str, default="UTC")),
         ("exclude", config_options.Type(list, default=[])),
+        ("enable_creation_date", config_options.Type(bool, default=False)),
     )
 
     def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]:
@@ -147,11 +148,15 @@ def on_page_markdown(
             logging.debug("Excluding page " + page.file.src_path)
             return markdown
 
+        # revision date
         revision_dates = self.util.get_revision_date_for_file(
-            path=page.file.abs_src_path,
+            commit_timestamp=self.util.get_git_commit_timestamp(
+                path=page.file.abs_src_path,
+                is_first_commit=False,
+                fallback_to_build_date=self.config.get("fallback_to_build_date"),
+            ),
             locale=self.config.get("locale", "en"),
             time_zone=self.config.get("time_zone", "UTC"),
-            fallback_to_build_date=self.config.get("fallback_to_build_date"),
         )
         revision_date = revision_dates[self.config["type"]]
 
@@ -162,13 +167,39 @@ def on_page_markdown(
             revision_date += revision_dates["iso_date"]
 
         page.meta["git_revision_date_localized"] = revision_date
-        return re.sub(
+        markdown = re.sub(
             r"\{\{\s*[page\.meta\.]*git_revision_date_localized\s*\}\}",
             revision_date,
             markdown,
             flags=re.IGNORECASE,
         )
 
+        # Creation date
+        if self.config.get("enable_creation_date"):
+            creation_dates = self.util.get_creation_date_for_file(
+                commit_timestamp=self.util.get_git_commit_timestamp(
+                    path=page.file.abs_src_path,
+                    is_first_commit=True,
+                    fallback_to_build_date=self.config.get("fallback_to_build_date"),
+                ),
+                locale=self.config.get("locale", "en"),
+                time_zone=self.config.get("time_zone", "UTC"),
+            )
+            creation_date = creation_dates[self.config["type"]]
+
+            if self.config["type"] == "timeago":
+                creation_date += creation_dates["iso_date"]
+
+            page.meta["git_creation_date_localized"] = creation_date
+            markdown = re.sub(
+                r"\{\{\s*[page\.meta\.]*git_creation_date_localized\s*\}\}",
+                creation_date,
+                markdown,
+                flags=re.IGNORECASE,
+            )
+
+        return markdown
+
     def on_post_build(self, config: Dict[str, Any], **kwargs) -> None:
         """
         Run on post build.

mkdocs_git_revision_date_localized_plugin/util.py

@@ -9,6 +9,7 @@
 from babel.dates import format_date, get_timezone
 from git import (
     Repo,
+    Git,
     GitCommandError,
     GitCommandNotFound,
     InvalidGitRepositoryError,
@@ -32,7 +33,7 @@ def __init__(self, config={}):
         self.config = config
         self.repo_cache = {}
 
-    def _get_repo(self, path: str):
+    def _get_repo(self, path: str) -> Git:
         if not os.path.isdir(path):
             path = os.path.dirname(path)
 
@@ -78,35 +79,41 @@ def _date_formats(
             % (loc_revision_date.isoformat(), locale),
         }
 
-    def get_revision_date_for_file(
-        self,
-        path: str,
-        locale: str = "en",
-        time_zone: str = "UTC",
-        fallback_to_build_date: bool = False,
-    ) -> Dict[str, str]:
+    def get_git_commit_timestamp(
+            self,
+            path: str,
+            is_first_commit: bool,
+            fallback_to_build_date: bool = False,
+    ) -> int:
         """
-        Determine localized date variants for a given file.
+        Get a list of commit dates in unix timestamp, starts with the most recent commit.
 
         Args:
+            is_first_commit (bool): if true, get the timestamp of the first commit,
+                                    else, get that of the most recent commit.
             path (str): Location of a markdown file that is part of a Git repository.
-            locale (str, optional): Locale code of language to use. Defaults to 'en'.
-            timezone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
         Returns:
-            dict: Localized date variants.
+            list: commit dates in unix timestamp, starts with the most recent commit.
         """
-        unix_timestamp = None
+
+        commit_timestamp = ""
 
         # perform git log operation
         try:
             if not self.fallback_enabled:
                 # Retrieve author date in UNIX format (%at)
                 # https://git-scm.com/docs/git-log#Documentation/git-log.txt-ematem
                 realpath = os.path.realpath(path)
-                unix_timestamp = self._get_repo(realpath).log(
-                    realpath, n=1, date="short", format="%at"
-                )
+                git = self._get_repo(realpath)
+                if is_first_commit:
+                    commit_timestamp = git.log(
+                        realpath, date="short", format="%at", diff_filter="A"
+                    )
+                else:
+                    commit_timestamp = git.log(
+                        realpath, date="short", format="%at", n=1
+                    )
         except (InvalidGitRepositoryError, NoSuchPathError) as err:
             if fallback_to_build_date:
                 logger.warning(
@@ -147,16 +154,36 @@ def get_revision_date_for_file(
                 raise err
 
         # create timestamp
-        if not unix_timestamp:
-            unix_timestamp = time.time()
+        if commit_timestamp == "":
+            commit_timestamp = time.time()
             if not self.fallback_enabled:
                 logger.warning(
                     "[git-revision-date-localized-plugin] '%s' has no git logs, using current timestamp"
                     % path
                 )
 
+        return int(commit_timestamp)
+
+    def get_revision_date_for_file(
+        self,
+        commit_timestamp: int,
+        locale: str = "en",
+        time_zone: str = "UTC",
+    ) -> Dict[str, str]:
+        """
+        Determine localized date variants for a given file.
+
+        Args:
+            commit_timestamp (int): most recent commit date in unix timestamp.
+            locale (str, optional): Locale code of language to use. Defaults to 'en'.
+            time_zone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+        Returns:
+            dict: Localized date variants.
+        """
+
         date_formats = self._date_formats(
-            unix_timestamp=unix_timestamp, time_zone=time_zone, locale=locale
+            unix_timestamp=commit_timestamp, time_zone=time_zone, locale=locale
         )
 
         # Wrap in <span> for styling
@@ -167,3 +194,34 @@ def get_revision_date_for_file(
             )
 
         return date_formats
+
+    def get_creation_date_for_file(
+        self,
+        commit_timestamp: int,
+        locale: str = "en",
+        time_zone: str = "UTC",
+    ) -> Dict[str, str]:
+        """
+        Determine localized date variants for a given file.
+
+        Args:
+            commit_timestamp (int): the first commit date in unix timestamp.
+            locale (str, optional): Locale code of language to use. Defaults to 'en'.
+            time_zone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+        Returns:
+            dict: Localized date variants.
+        """
+
+        date_formats = self._date_formats(
+            unix_timestamp=commit_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)
+            )
+
+        return date_formats

tests/fixtures/basic_project/docs/page_with_tag.md

@@ -1,3 +1,5 @@
 # test page
 
 Tag <mark>\{\{ git_revision_date_localized \}\}</mark> renders as: {{ git_revision_date_localized }}
+
+Tag <mark>\{\{ git_creation_date_localized \}\}</mark> renders as: {{ git_creation_date_localized }}

tests/fixtures/basic_project/mkdocs_creation_date.yml

@@ -0,0 +1,7 @@
+site_name: test gitrevisiondatelocalized_plugin
+use_directory_urls: true
+
+plugins:
+    - search
+    - git-revision-date-localized:
+        enable_creation_date: True

tests/test_builds.py

@@ -120,6 +120,9 @@ def setup_commit_history(testproject_path):
     os.chdir(testproject_path)
 
     try:
+        repo.git.add("docs/page_with_tag.md")
+        repo.git.commit(message="add homepage", author=author, date="1500854705 -0700")
+
         repo.git.add("mkdocs.yml")
         repo.git.commit(message="add mkdocs", author=author)
 
@@ -139,8 +142,12 @@ def setup_commit_history(testproject_path):
         repo.git.commit(message="second page", author=author)
         repo.git.add("docs/index.md")
         repo.git.commit(message="homepage", author=author)
+
+        file_name = os.path.join(testproject_path, "docs/page_with_tag.md")
+        with open(file_name, "a") as the_file:
+            the_file.write("awa\n")
         repo.git.add("docs/page_with_tag.md")
-        repo.git.commit(message="homepage", author=author)
+        repo.git.commit(message="update homepage", author=author)
         os.chdir(cwd)
     except:
         os.chdir(cwd)
@@ -195,13 +202,31 @@ def validate_build(testproject_path, plugin_config: dict = {}):
 
     repo = Util(str(testproject_path / "docs"))
     date_formats = repo.get_revision_date_for_file(
-        path=str(testproject_path / "docs/page_with_tag.md"),
+        commit_timestamp=repo.get_git_commit_timestamp(
+            path=str(testproject_path / "docs/page_with_tag.md"),
+            is_first_commit=False,
+            fallback_to_build_date=plugin_config.get("fallback_to_build_date"),
+        ),
         locale=plugin_config.get("locale"),  # type: ignore
-        fallback_to_build_date=plugin_config.get("fallback_to_build_date"),  # type: ignore
     )
 
     searches = [x in contents for x in date_formats.values()]
-    assert any(searches), "No correct date formats output was found"
+    assert any(searches), "No correct revision date formats output was found"
+
+    if plugin_config.get("enable_creation_date"):
+        commit_timestamp=repo.get_git_commit_timestamp(
+            path=str(testproject_path / "docs/page_with_tag.md"),
+            is_first_commit=True,
+            fallback_to_build_date=plugin_config.get("fallback_to_build_date"),
+        )
+        assert commit_timestamp == 1500854705
+        date_formats = repo.get_revision_date_for_file(
+            commit_timestamp=commit_timestamp,
+            locale=plugin_config.get("locale"),  # type: ignore
+        )
+
+        searches = [x in contents for x in date_formats.values()]
+        assert any(searches), "No correct creation date formats output was found"
 
 
 def validate_mkdocs_file(temp_path: str, mkdocs_yml_file: str):
@@ -270,6 +295,11 @@ def test_build_no_options(tmp_path):
     validate_mkdocs_file(tmp_path, "tests/fixtures/basic_project/mkdocs.yml")
 
 
+def test_build_creation_date(tmp_path):
+    # Enable plugin with no extra options set
+    validate_mkdocs_file(tmp_path, "tests/fixtures/basic_project/mkdocs_creation_date.yml")
+
+
 def test_build_locale_plugin(tmp_path):
     # Enable plugin with plugin locale set to 'nl'
     validate_mkdocs_file(