Merge pull request #45 from RDIL/master

Several enhancements

Author: timvink

.flake8

@@ -0,0 +1,2 @@
+[flake8]
+ignore = E501,E722

CONTRIBUTING.md

@@ -11,9 +11,12 @@ Thanks for considering to contribute to this project! Some guidelines:
 
 There are multiple mkdocs plugins that use information from the local git repo. 
 
-In order to simplify user experience and maintenance, I intend to merge functionality in this plugin with [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin). See https://github.com/timvink/mkdocs-git-authors-plugin/issues/16 for a similar roadmap issue with more details.
+In order to simplify user experience and maintenance,
+I intend to merge functionality in this plugin with [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin).
+See https://github.com/timvink/mkdocs-git-authors-plugin/issues/16 for a similar roadmap issue with more details.
 
-That means not extending the functionality of this plugin, but rather aiming to create a simple, stable release that can go into 'maintenance mode'. If users want more information extracted from GIT, they can go to [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin).
+That means not extending the functionality of this plugin, but rather aiming to create a simple, stable release that can go into 'maintenance mode'.
+If users want more information extracted from Git, they can go to [mkdocs-git-authors-plugin](https://github.com/timvink/mkdocs-git-authors-plugin).
 
 ## Unit Tests
 
@@ -27,7 +30,7 @@ pytest --cov=mkdocs_git_revision_date_localized_plugin --cov-report term-missing
 
 If it makes sense, writing tests for your PRs is always appreciated and will help get them merged.
 
-In addition, this project uses [pyflakes](https://github.com/PyCQA/pyflakes) for static code checking:
+In addition, this project uses [flake8](https://github.com/PyCQA/flake8) for static code checking:
 
 ```python
 pip install pyflakes
@@ -36,7 +39,8 @@ pyflakes tests/ mkdocs_git_revision_date_localized_plugin/
 
 ## Manual testing
 
-To quickly serve a test website with your latest changes to the plugin use the sites in our tests suite. For example:
+To quickly serve a test website with your latest changes to the plugin use the sites in our tests suite.
+For example:
 
 ```python
 pip install -r tests/test_requirements.txt
@@ -46,6 +50,7 @@ mkdocs serve -f tests/fixtures/basic_project/mkdocs.yml
 
 ## Code Style
 
-Make sure your code *roughly* follows [PEP-8](https://www.python.org/dev/peps/pep-0008/) and keeps things consistent with the rest of the code.
+Make sure your code *roughly* follows [PEP-8](https://www.python.org/dev/peps/pep-0008/)
+and keeps things consistent with the rest of the code.
 
-We use google-style docstrings.
+We use Google-style docstrings.

MANIFEST.in

@@ -1,2 +1,2 @@
 include mkdocs_git_revision_date_localized_plugin/js/*.js
-include mkdocs_git_revision_date_localized_plugin/css/*.css
+include mkdocs_git_revision_date_localized_plugin/css/*.css

mkdocs_git_revision_date_localized_plugin/ci.py

@@ -2,13 +2,13 @@
 import logging
 
 
-def raise_ci_warnings(repo):
+def raise_ci_warnings(repo) -> None:
     """
-    raise warnings when users use mkdocs-git-revision-date-localized-plugin
-    on CI build runners
+    Raise warnings when users use mkdocs-git-revision-date-localized-plugin
+    on CI build runners.
 
     Args:
-        repo (GitPython.git.repo): The Git repo object
+        repo (GitPython.git.repo): The Git repo object.
     """
 
     if not is_shallow_clone(repo):
@@ -17,36 +17,39 @@ def raise_ci_warnings(repo):
     n_commits = commit_count(repo)
 
     # Gitlab Runners
-    if os.environ.get("GITLAB_CI") and n_commits < 50:
+    if os.getenv("GITLAB_CI") is not None 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.
+                [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:
+    if os.getenv("GITHUB_ACTIONS") is not None 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
+                [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:
+    if os.getenv("CI") is not None 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.
+                [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').
@@ -55,26 +58,27 @@ def raise_ci_warnings(repo):
 
     # Azure Devops Pipeline
     # Does not limit fetch-depth by default
-    if os.environ.get("Agent.Source.Git.ShallowFetchDepth", 10e99) < n_commits:
+    if int(os.getenv("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.
+                [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:
+def commit_count(repo) -> int:
     """
-    Helper function to determine the number of commits in a repository
+    Helper function to determine the number of commits in a repository.
 
     Args:
-        repo (GitPython.Repo.git): Repository
+        repo (GitPython.Repo.git): Repository.
 
     Returns:
-        count (int): Number of commits
+        count (int): Number of commits.
     """
     refs = repo.for_each_ref().split("\n")
     refs = [x.split()[0] for x in refs]

mkdocs_git_revision_date_localized_plugin/css/timeago.css

@@ -1,11 +1,11 @@
 /* 
-timeago output is dynamic, which breaks when you print a page
-This ensures fallback to type "iso_date" when printing
-*/
+ * timeago output is dynamic, which breaks when you print a page.
+ * This ensures fallback to type "iso_date" when printing.
+ */
 
 .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 } 
-}
+}

mkdocs_git_revision_date_localized_plugin/js/timeago_mkdocs_material.js

@@ -4,14 +4,14 @@
 if (
     typeof app !== "undefined" && 
     typeof app.document$ !== "undefined"
-    ) {
+) {
     app.document$.subscribe(function() {
         var nodes = document.querySelectorAll('.timeago');
         var locale = nodes[0].getAttribute('locale');
         timeago.render(nodes, locale);
     })
 } else {
-     var nodes = document.querySelectorAll('.timeago');
-     var locale = nodes[0].getAttribute('locale');
-     timeago.render(nodes, locale);
-}
+    var nodes = document.querySelectorAll('.timeago');
+    var locale = nodes[0].getAttribute('locale');
+    timeago.render(nodes, locale);
+}

mkdocs_git_revision_date_localized_plugin/plugin.py

@@ -12,17 +12,21 @@
 # package modules
 from mkdocs_git_revision_date_localized_plugin.util import Util
 
+from typing import Any, Dict
+
 HERE = os.path.dirname(os.path.abspath(__file__))
 
+
 class GitRevisionDateLocalizedPlugin(BasePlugin):
     config_scheme = (
         ("fallback_to_build_date", config_options.Type(bool, default=False)),
         ("locale", config_options.Type(str, default=None)),
         ("type", config_options.Type(str, default="date")),
         ("timezone", config_options.Type(str, default="UTC")),
+        ("excluded_page_titles", config_options.Type(list, default=[]))
     )
 
-    def on_config(self, config: config_options.Config, **kwargs) -> dict:
+    def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]:
         """
         Determine which locale to use.
 
@@ -121,6 +125,12 @@ def on_page_markdown(
             str: Markdown source text of page as string
         """
 
+        excluded_titles = self.config.get("excluded_page_titles", [])
+        if page.title in excluded_titles:
+            logging.debug("Excluding page " + page.url)
+            # page is excluded
+            return markdown
+
         revision_dates = self.util.get_revision_date_for_file(
             path=page.file.abs_src_path,
             locale=self.config.get("locale", "en"),
@@ -143,12 +153,14 @@ def on_page_markdown(
             flags=re.IGNORECASE,
         )
 
-
-    def on_post_build(self, config, **kwargs):
-
+    def on_post_build(self, config: Dict[str, Any], **kwargs) -> None:
+        """
+        Run on post build.
+        Adds the timeago assets to the build.
+        """
         # Add timeago files:
         if self.config.get("type") == "timeago":
-            files = ['js/timeago.min.js', 'js/timeago_mkdocs_material.js', 'css/timeago.css']
+            files = ["js/timeago.min.js", "js/timeago_mkdocs_material.js", "css/timeago.css"]
             for file in files:
                 dest_file_path = os.path.join(config["site_dir"], file)
                 src_file_path = os.path.join(HERE, file)

mkdocs_git_revision_date_localized_plugin/util.py

@@ -8,6 +8,8 @@
 from babel.dates import format_date, get_timezone
 from git import Repo, GitCommandError, GitCommandNotFound, InvalidGitRepositoryError, NoSuchPathError
 
+from typing import Any, Dict
+
 logger = logging.getLogger("mkdocs.plugins")
 
 
@@ -33,17 +35,17 @@ def _get_repo(self, path: str):
     @staticmethod
     def _date_formats(
         unix_timestamp: float, locale: str = "en", time_zone: str = "UTC"
-    ) -> dict:
+    ) -> Dict[str, Any]:
         """
         Returns different date formats / types.
 
         Args:
-            unix_timestamp (float): a timestamp in seconds since 1970
+            unix_timestamp (float): A timestamp in seconds since 1970.
             locale (str): 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)
+            time_zone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
         Returns:
-            dict: different date formats
+            dict: Different date formats.
         """
         utc_revision_date = datetime.utcfromtimestamp(int(unix_timestamp))
         loc_revision_date = utc_revision_date.replace(
@@ -52,9 +54,10 @@ def _date_formats(
 
         return {
             "date": format_date(loc_revision_date, format="long", locale=locale),
-            "datetime": format_date(loc_revision_date, format="long", locale=locale)
-            + " "
-            + loc_revision_date.strftime("%H:%M:%S"),
+            "datetime": " ".join([
+                format_date(loc_revision_date, format="long", locale=locale),
+                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>'
@@ -67,17 +70,17 @@ def get_revision_date_for_file(
         locale: str = "en",
         time_zone: str = "UTC",
         fallback_to_build_date: bool = False,
-    ) -> dict:
+    ) -> Dict[str, str]:
         """
         Determine localized date variants for a given file
 
         Args:
-            path (str): Location of a markdownfile that is part of a GIT repository
+            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) 
+            timezone (str): Timezone database name (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
         Returns:
-            dict: localized date variants
+            dict: Localized date variants.
         """
 
         unix_timestamp = None

requirements.txt

@@ -0,0 +1,3 @@
+mkdocs>=1.0
+GitPython
+babel>=2.7.0

setup.py

@@ -1,13 +1,20 @@
 from setuptools import find_packages, setup
 
-with open("README.md", "r") as fh:
-    long_description = fh.read()
+file = open("README.md", "r")
+LONG_DESCRIPTION = file.read()
+file.close()
+
+file = open("requirements.txt", "r")
+DEPENDENCIES = file.readlines()
+file.close()
+
+del file
 
 setup(
     name="mkdocs-git-revision-date-localized-plugin",
     version="0.7.4",
     description="Mkdocs plugin that enables displaying the localized date of the last git modification of a markdown file.",
-    long_description=long_description,
+    long_description=LONG_DESCRIPTION,
     long_description_content_type="text/markdown",
     keywords="mkdocs git date timeago babel plugin",
     url="https://github.com/timvink/mkdocs-git-revision-date-localized-plugin",
@@ -21,7 +28,7 @@
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
-    install_requires=["mkdocs>=1.0", "GitPython", "babel>=2.7.0"],
+    install_requires=DEPENDENCIES,
     packages=find_packages(),
     entry_points={
         "mkdocs.plugins": [

tests/test_builds.py

@@ -1,5 +1,5 @@
 """
-Tests running builds on different fresh mkdocs projects
+Tests running builds on different fresh mkdocs projects.
 
 Note that pytest offers a `tmp_path` fixture that we use here.
 You can reproduce locally with:
@@ -196,8 +196,8 @@ 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"),
-        locale=plugin_config.get("locale"),
-        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()]
@@ -360,7 +360,7 @@ def test_build_with_timezone(tmp_path):
 
 def test_git_in_docs_dir(tmp_path):
     """
-    In https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/pull/31 
+    In https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/pull/31
     a use case is described where `.git` dir lives in `docs/`
     """
 
@@ -434,10 +434,10 @@ def test_low_fetch_depth(tmp_path, caplog):
     os.environ["GITLAB_CI"] = "1"
     result = build_docs_setup(cloned_folder)
     assert result.exit_code == 0
-    assert "Running on a gitlab runner" in caplog.text
+    assert "Running on a GitLab runner" in caplog.text
 
     del os.environ["GITLAB_CI"]
     os.environ["GITHUB_ACTIONS"] = "1"
     result = build_docs_setup(cloned_folder)
     assert result.exit_code == 0
-    assert "Running on github actions might" in caplog.text
+    assert "Running on GitHub Actions might" in caplog.text

tests/test_requirements.txt

@@ -2,4 +2,4 @@ pytest
 pytest-cov
 codecov
 click
-mkdocs-material
+mkdocs-material