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

Author: timvink

docs/howto/specify-locale.md

@@ -0,0 +1,73 @@
+# Specify a locale
+
+`locale` is a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code that `git-revision-date-localized` uses to display dates in your preferred language.
+
+For example:
+
+```yaml
+April 27, 2021                # `locale: en` with `type: date` (default)
+April 27, 2021 13:11:28       # `locale: en` with `type: datetime`
+2 weeks ago                   # `locale: en` with `type: timeago`
+27 de marzo de 2021           # `locale: es` with `type: date`
+27 de marzo de 2021 13:57:28  # `locale: es` with `type: datetime`
+hace 2 semanas                # `locale: es` with `type: timeago`
+```
+
+You can set the `locale` in different locations, both for your entire site and on a per-page basis. If specified multiple times `git-revision-date-localized` will use the `locale` that is most specific to a page.
+
+Here's the order of priority:
+
+## 1. Page locale set by the `i18n` plugin
+
+The [mkdocs-static-i18n](https://github.com/ultrabug/mkdocs-static-i18n) plugin helps you support multiple language versions of your site. When enabled, `i18n` will add a `locale` attribute to each markdown page that `git-revision-date-localized` will use.
+
+## 2. Page locale set by metadata
+
+The [Metadata](https://python-markdown.github.io/extensions/meta_data/) adds the ability to attach arbitrary key-value pairs to a document via front matter written in YAML syntax before the Markdown. Enable it via mkdocs.yml:
+
+```yaml
+# mkdocs.yml
+markdown_extensions:
+  - meta
+```
+
+If set `git-revision-date-localized` will use the `locale` key in a markdown page's frontmatter, for example:
+
+```md
+---
+locale: en
+---
+
+# Page title
+```
+
+## 3. Site locale set by your theme
+
+Some [MkDocs Themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) support [localization](https://www.mkdocs.org/user-guide/localizing-your-theme/) by setting a `locale` or `language` option. See for example the [Changing the language](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/) section of [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+
+Example:
+
+```yaml
+# mkdocs.yml
+theme:
+  language: en
+```
+
+## 4. Site locale set by this plugin
+
+Of course `locale` is an [option](../options.md) for this plugin also.
+
+```yaml
+plugins:
+- git-revision-date-localized:
+    locale: en
+```
+
+## 5. Fallback locale
+
+If no `locale` is specified anywhere, the fallback is English (`en`).
+
+!!! info "Supported locales"
+    - When used in combination with `type: date` or `type: datetime`, translation is done using [babel](https://github.com/python-babel/babel) which supports [these locales](http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html)
+
+    - When used in combination with `type: timeago` then [timeago.js](https://github.com/hustcc/timeago.js) is added to your website, which supports [these locales](https://github.com/hustcc/timeago.js/tree/master/src/lang). If you specify a locale not supported by timeago.js, the fallback is English (`en`)

docs/options.md

@@ -33,13 +33,18 @@ November 28, 2019 13:57:28  # type: datetime
 
 Default is `UTC`. Specify a time zone database name ([reference](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). This option is especially relevant when using `type: datetime` and `type: iso_datetime`. Note that when using [timeago](http://timeago.yarp.com/) (with `type: timeago`) any difference in time zones between server and client will be handled automatically.
 
-## `locale`
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        timezone: Europe/Amsterdam
+  ```
+
 
-Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language.
+## `locale`
 
-- When not set, this plugin will look for `locale` or `language` options set in your theme. If also not set, the fallback is English (`en`)
-- When used in combination with `type: date` or `type: datetime`, translation is done using [babel](https://github.com/python-babel/babel) which supports [these locales](http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html)
-- When used in combination with `type: timeago` then [timeago.js](https://github.com/hustcc/timeago.js) is added to your website, which supports [these locales](https://github.com/hustcc/timeago.js/tree/master/src/lang). If you specify a locale not supported by timeago.js, the fallback is English (`en`)
+Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language. Note this plugin supports many different ways to [specify the locale](howto/specify-locale.md), but if not specified anywhere the fallback is English (`en`).
 
 Example outputs:
 
@@ -52,14 +57,40 @@ April 27, 2021 13:11:28       # `locale: en` with `type: datetime`
 hace 2 semanas                # `locale: es` with `type: timeago`
 ```
 
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        locale: en
+  ```
+
+
 ## `fallback_to_build_date`
 
 Default is `false`. Enables falling back to the time when `mkdocs build` was executed *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.
 
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        fallback_to_build_date: true
+  ```
+
+
 ## `enable_creation_date`
 
 Default is `false` (because it has a small effect on build time). Enables a *Created* date variables, see [available-variables.md]. This will also add a created date at the bottom of each page in `mkdocs-material` as it has native support (see [overriding a theme](howto/override-a-theme.md)).
 
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        enable_creation_date: true
+  ```
+
 ## `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.yml

@@ -8,6 +8,7 @@ nav:
   - index.md
   - available-variables.md
   - How to:
+      - howto/specify-locale.md
       - howto/custom-styling.md
       - howto/override-a-theme.md
   - options.md

mkdocs_git_revision_date_localized_plugin/ci.py

@@ -20,6 +20,7 @@ def raise_ci_warnings(repo) -> None:
 
     n_commits = commit_count(repo)
 
+
     # Gitlab Runners
     if os.getenv("GITLAB_CI") is not None and n_commits < 50:
         # Default is GIT_DEPTH of 50 for gitlab
@@ -85,11 +86,7 @@ def commit_count(repo) -> int:
     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 int(repo.rev_list('--count','HEAD'))
 
 
 def is_shallow_clone(repo) -> bool:

mkdocs_git_revision_date_localized_plugin/plugin.py

@@ -14,12 +14,14 @@
 from mkdocs.plugins import BasePlugin
 from mkdocs.structure.nav import Page
 from mkdocs.utils import copy_file
+from mkdocs.exceptions import ConfigurationError
 
 # package modules
 from mkdocs_git_revision_date_localized_plugin.util import Util
 from mkdocs_git_revision_date_localized_plugin.exclude import exclude
 
 from typing import Any, Dict
+from collections import OrderedDict
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 
@@ -59,17 +61,15 @@ def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]:
         if not self.config.get('enabled'):
             return config
 
+        assert self.config['type'] in ["date","datetime","iso_date","iso_datetime","timeago"]
+
         self.util = Util(config=self.config)
 
         # Save last commit timestamp for entire site
         self.last_site_revision_timestamp = self.util.get_git_commit_timestamp(
             config.get('docs_dir')
         )
 
-        # Get locale settings - might be added in future mkdocs versions
-        # see: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues/24
-        mkdocs_locale = config.get("locale", None)
-
         # Get locale from plugin configuration
         plugin_locale = self.config.get("locale", None)
 
@@ -106,14 +106,15 @@ def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]:
                 "Locale not set in plugin. Fallback to theme configuration: %s"
                 % locale_set
             )
-        # Third prio is mkdocs locale (which might be added in the future)
-        elif mkdocs_locale:
-            locale_set = mkdocs_locale
-            logging.debug("Using locale from mkdocs configuration: %s" % locale_set)
+        # Lastly, fallback is English
         else:
             locale_set = "en"
             logging.debug("No locale set. Fallback to: %s" % locale_set)
 
+        # Validate locale
+        locale_set = str(locale_set)
+        assert len(locale_set) == 2, "locale must be a 2 letter code, see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes"
+
         # set locale also in plugin configuration
         self.config["locale"] = locale_set
 
@@ -127,6 +128,14 @@ def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]:
             ]
             config["extra_css"] = ["css/timeago.css"] + config["extra_css"]
 
+        # Compatibility with mkdocs-static-i18n
+        plugins = [*OrderedDict(config["plugins"])]
+        if "i18n" in plugins:
+            if plugins.index("git-revision-date-localized") < plugins.index("i18n"):
+                msg = "[git-revision-date-localized] should be defined after the i18n plugin in your mkdocs.yml file. "
+                msg += "This is because i18n adds a 'locale' variable to markdown pages that this plugin supports."
+                raise ConfigurationError(msg)
+        
         return config
 
     def on_page_markdown(
@@ -160,14 +169,41 @@ def on_page_markdown(
             logging.debug("Excluding page " + page.file.src_path)
             return markdown
 
+        # Find the locale
+
+        # First prio is use mkdocs-static-i18n locale if set
+        try:
+            locale = page.locale
+
+        except AttributeError:
+            locale = None
+
+        # Second prio is a frontmatter variable 'locale' set in the markdown
+        if not locale:
+            if "locale" in page.meta:
+                locale = page.meta['locale']
+
+        # Finally, if no page locale set, we take the locale determined on_config()
+        if not locale:
+            locale = self.config.get("locale")
+        
+        # MkDocs supports 2-letter and 5-letter locales
+        # https://www.mkdocs.org/user-guide/localizing-your-theme/#supported-locales
+        # We need the 2 letter variant
+        if len(locale) == 5:
+            locale = locale[:2]
+        assert len(locale) == 2, "locale must be a 2 letter code, see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes"
+        
+
+
         # Retrieve git commit timestamp
         last_revision_timestamp = self.util.get_git_commit_timestamp(
                 path=page.file.abs_src_path,
                 is_first_commit=False,
         )
 
         # Last revision date
-        revision_dates = self.util.get_date_formats_for_timestamp(last_revision_timestamp)
+        revision_dates = self.util.get_date_formats_for_timestamp(last_revision_timestamp, locale=locale, add_spans=True)
         revision_date = revision_dates[self.config["type"]]
 
         # timeago output is dynamic, which breaks when you print a page
@@ -179,7 +215,7 @@ def on_page_markdown(
         # Add to page meta information, for developers
         # Include variants without the CSS <span> elements (raw date strings)
         page.meta["git_revision_date_localized"] = revision_date
-        revision_dates_raw = self.util.get_date_formats_for_timestamp(last_revision_timestamp, add_spans=False)
+        revision_dates_raw = self.util.get_date_formats_for_timestamp(last_revision_timestamp, locale=locale, add_spans=False)
         for date_type, date_string in revision_dates_raw.items():
             page.meta["git_revision_date_localized_raw_%s" % date_type] = date_string
 
@@ -192,12 +228,12 @@ def on_page_markdown(
         )
 
         # Also add site last updated information, for developers
-        site_dates = self.util.get_date_formats_for_timestamp(self.last_site_revision_timestamp)
+        site_dates = self.util.get_date_formats_for_timestamp(self.last_site_revision_timestamp, locale=locale, add_spans=True)
         site_date = site_dates[self.config["type"]]
         if self.config["type"] == "timeago":
             site_date += site_dates["iso_date"]
         page.meta["git_site_revision_date_localized"] = site_date
-        site_dates_raw = self.util.get_date_formats_for_timestamp(self.last_site_revision_timestamp, add_spans=False)
+        site_dates_raw = self.util.get_date_formats_for_timestamp(self.last_site_revision_timestamp, locale=locale, add_spans=False)
         for date_type, date_string in site_dates_raw.items():
             page.meta["git_site_revision_date_localized_raw_%s" % date_type] = date_string
 
@@ -222,7 +258,7 @@ def on_page_markdown(
         )
 
         # Creation date formats
-        creation_dates = self.util.get_date_formats_for_timestamp(first_revision_timestamp)
+        creation_dates = self.util.get_date_formats_for_timestamp(first_revision_timestamp, locale=locale, add_spans=True)
         creation_date = creation_dates[self.config["type"]]
 
         # timeago output is dynamic, which breaks when you print a page
@@ -234,7 +270,7 @@ def on_page_markdown(
         # Add to page meta information, for developers
         # Include variants without the CSS <span> elements (raw date strings)
         page.meta["git_creation_date_localized"] = creation_date
-        creation_dates_raw = self.util.get_date_formats_for_timestamp(first_revision_timestamp, add_spans=False)
+        creation_dates_raw = self.util.get_date_formats_for_timestamp(first_revision_timestamp, locale=locale, add_spans=False)
         for date_type, date_string in creation_dates_raw.items():
             page.meta["git_creation_date_localized_raw_%s" % date_type] = date_string
 

mkdocs_git_revision_date_localized_plugin/util.py

@@ -178,23 +178,24 @@ def get_git_commit_timestamp(
     def get_date_formats_for_timestamp(
         self,
         commit_timestamp: int,
-        add_spans: bool = True
+        locale: str,
+        add_spans: bool = True,
     ) -> Dict[str, str]:
         """
         Determine localized date variants for a given timestamp.
 
         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).
+            add_spans: Wraps output in <span> elements with unique classes for easy CSS formatting
 
         Returns:
             dict: Localized date variants.
         """
         date_formats = self._date_formats(
             unix_timestamp=commit_timestamp, 
             time_zone=self.config.get("timezone"),
-            locale=self.config.get("locale")
+            locale=locale
         )
         if add_spans:
             date_formats = self.add_spans(date_formats)

tests/fixtures/basic_project/docs/index.md

@@ -1,3 +1,7 @@
+---
+locale: en
+---
+
 # Test home page
 
 Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

tests/fixtures/basic_project/mkdocs_meta.yml

@@ -0,0 +1,9 @@
+site_name: test gitrevisiondatelocalized_plugin
+use_directory_urls: true
+
+plugins:
+    - search
+    - git-revision-date-localized
+
+markdown_extensions:
+  - meta