Add exclude pages option, see #55

Author: timvink

docs/options.md

@@ -9,6 +9,8 @@ plugins:
         show_line_count: true
         count_empty_lines: true
         fallback_to_empty: false
+        exclude:
+            - index.md
 ```
 
 ## `show_contribution`
@@ -33,3 +35,18 @@ If this option is set to `true` (default: `false`) empty lines will count toward
 ## `fallback_to_empty`
 
 If this option is set to `true` (default: `false`) the plugin will work even outside of a proper Git environment, prompting a warning when it's the case, and resulting in empty author list.
+
+## `exclude`
+
+Default is empty. Specify a list of page source paths (one per line) that should not have author(s) included (excluded from processing by this plugin). This can be useful for example to remove the authors 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:
+
+```yaml
+# mkdocs.yml
+plugins:
+  - git-authors:
+      exclude:
+        - index.md
+        - subfolder/page.md
+        - another_page.md
+        - folder/*
+```

mkdocs_git_authors_plugin/exclude.py

@@ -0,0 +1,43 @@
+"""
+Module to assist exclude certain files being processed by plugin.
+Inspired by https://github.com/apenwarr/mkdocs-exclude
+"""
+import os
+import fnmatch
+from typing import List
+
+
+def exclude(src_path: str, globs: List[str]) -> bool:
+    """
+    Determine if a src_path should be excluded.
+    Supports globs (e.g. folder/* or *.md).
+    Credits: code inspired by / adapted from
+    https://github.com/apenwarr/mkdocs-exclude/blob/master/mkdocs_exclude/plugin.py
+    Args:
+        src_path (src): Path of file
+        globs (list): list of globs
+    Returns:
+        (bool): whether src_path should be excluded
+    """
+    assert isinstance(src_path, str)
+    assert isinstance(globs, list)
+
+    for g in globs:
+        if fnmatch.fnmatchcase(src_path, g):
+            return True
+
+        # Windows reports filenames as eg.  a\\b\\c instead of a/b/c.
+        # To make the same globs/regexes match filenames on Windows and
+        # other OSes, let's try matching against converted filenames.
+        # On the other hand, Unix actually allows filenames to contain
+        # literal \\ characters (although it is rare), so we won't
+        # always convert them.  We only convert if os.sep reports
+        # something unusual.  Conversely, some future mkdocs might
+        # report Windows filenames using / separators regardless of
+        # os.sep, so we *always* test with / above.
+        if os.sep != "/":
+            src_path_fix = src_path.replace(os.sep, "/")
+            if fnmatch.fnmatchcase(src_path_fix, g):
+                return True
+
+    return False

mkdocs_git_authors_plugin/plugin.py

@@ -7,6 +7,7 @@
 from . import util
 from .git.repo import Repo
 from mkdocs_git_authors_plugin.ci import raise_ci_warnings
+from mkdocs_git_authors_plugin.exclude import exclude
 
 logger = logging.getLogger("mkdocs.plugins")
 
@@ -15,7 +16,8 @@ class GitAuthorsPlugin(BasePlugin):
         ("show_contribution", config_options.Type(bool, default=False)),
         ("show_line_count", config_options.Type(bool, default=False)),
         ("count_empty_lines", config_options.Type(bool, default=True)),
-        ("fallback_to_empty", config_options.Type(bool, default=False))
+        ("fallback_to_empty", config_options.Type(bool, default=False)),
+        ("exclude", config_options.Type(list, default=[])),
         # ('sort_authors_by_name', config_options.Type(bool, default=True)),
         # ('sort_reverse', config_options.Type(bool, default=False))
     )
@@ -115,6 +117,11 @@ def on_page_content(self, html, page, config, files, **kwargs):
         Returns:
             str: HTML text of page as string
         """
+        # Exclude pages specified in config
+        excluded_pages = self.config.get("exclude", [])
+        if exclude(page.file.src_path, excluded_pages):
+            logging.debug("on_page_html, Excluding page " + page.file.src_path)
+            return html
 
         list_pattern = re.compile(
             r"\{\{\s*git_site_authors\s*\}\}", flags=re.IGNORECASE
@@ -146,6 +153,13 @@ def on_page_markdown(self, markdown, page, config, files, **kwargs):
         Returns:
             str: Markdown source text of page as string
         """
+
+        # Exclude pages specified in config
+        excluded_pages = self.config.get("exclude", [])
+        if exclude(page.file.src_path, excluded_pages):
+            logging.debug("on_page_markdown, Excluding page " + page.file.src_path)
+            return markdown
+
         pattern_authors_summary = re.compile(
             r"\{\{\s*git_authors_summary\s*\}\}", flags=re.IGNORECASE
         )
@@ -195,6 +209,12 @@ def on_page_context(self, context, page, config, nav, **kwargs):
         if self._fallback:
             return context
 
+        # Exclude pages specified in config
+        excluded_pages = self.config.get("exclude", [])
+        if exclude(page.file.src_path, excluded_pages):
+            logging.debug("on_page_context, Excluding page " + page.file.src_path)
+            return context
+
         path = page.file.abs_src_path
         page_obj = self.repo().page(path)
         authors = page_obj.get_authors()

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="mkdocs-git-authors-plugin",
-    version="0.4.1",
+    version="0.5",
     description="Mkdocs plugin to display git authors of a page",
     long_description=long_description,
     long_description_content_type="text/markdown",

tests/basic_setup/mkdocs_exclude.yml

@@ -0,0 +1,8 @@
+site_name: test gitauthors_plugin
+use_directory_urls: true
+
+plugins:
+    - search
+    - git-authors:
+        exclude:
+            - page_with_tag.md

tests/test_basic.py

@@ -68,6 +68,21 @@ def test_basic_working(tmp_path):
     assert re.search("<span class='git-page-authors", contents)
 
 
+def test_exclude_working(tmp_path):
+
+    result = build_docs_setup("tests/basic_setup/mkdocs_exclude.yml", tmp_path)
+    assert result.exit_code == 0, (
+        "'mkdocs build' command failed. Error: %s" % result.stdout
+    )
+
+    page_file = tmp_path / "page_with_tag/index.html"
+    assert page_file.exists(), "%s does not exist" % page_file
+
+    contents = page_file.read_text()
+    assert not re.search("<span class='git-page-authors", contents)
+
+
+
 def test_project_with_no_commits(tmp_path):
     """
     Structure: