Improve the contribs plugin (#16)

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.9] - 2022-10-02
+- Improves the `contributors` plugin:
+- - Adds the possibility to exclude contributor information (for example to not display
+    contributions from bots).
+- - Adds the possibility to merge contributors' information
+    for cases in which the same person commits using two different email addresses.
+- Resolves a small issue in pip package resolution.
+
 ## [0.0.8] - 2022-10-01
 - Improves the Gantt extension:
 - - now supports multiple periods in the same row

neoteroi/contribs/__init__.py

@@ -9,7 +9,7 @@
 import logging
 from datetime import datetime
 from pathlib import Path
-from typing import List
+from typing import List, Optional
 
 from mkdocs.config import config_options as c
 from mkdocs.plugins import BasePlugin
@@ -37,7 +37,38 @@ def __init__(self) -> None:
         super().__init__()
         self._contribs_reader = GitContributionsReader()
 
+    def _read_contributor_merge_with(self, contributor_info) -> Optional[str]:
+        return contributor_info.get("merge_with")
+
+    def _handle_merge_contributor_info(
+        self,
+        contributors: List[Contributor],
+        contributor: Contributor,
+        contributor_info: dict,
+    ) -> bool:
+        """
+        Handles an optional "merge_with" property in the contributor info object
+        (from configuration), returning true if the given contributor (from repo
+        information) should be discarded (its commits count was merged with another
+        one).
+        """
+        assert contributor.email == contributor_info.get(
+            "email"
+        ), "The contributor info object must match the contributor object."
+        merge_with = contributor_info.get("merge_with")
+
+        if merge_with:
+            parent = next(
+                (item for item in contributors if item.email == merge_with),
+                None,
+            )
+            if parent:
+                parent.count += contributor.count
+                return True
+        return False
+
     def _get_contributors(self, page_file: File) -> List[Contributor]:
+        results = []
         contributors = self._contribs_reader.get_contributors(
             Path("docs") / page_file.src_path
         )
@@ -53,7 +84,20 @@ def _get_contributors(self, page_file: File) -> List[Contributor]:
             if contributor_info:
                 contributor.image = contributor_info.get("image")
 
-        return contributors
+                if contributor_info.get("ignore"):
+                    # ignore the contributor's information (can be useful for bots)
+                    continue
+
+                # should contributor information be merged with another object?
+                if self._handle_merge_contributor_info(
+                    contributors, contributor, contributor_info
+                ):
+                    # skip this item as it was merged with another one
+                    continue
+
+            results.append(contributor)
+
+        return results
 
     def _get_last_commit_date(self, page_file: File) -> datetime:
         return self._contribs_reader.get_last_commit_date(

setup.py

@@ -8,7 +8,7 @@ def readme():
 
 setup(
     name="neoteroi-mkdocs",
-    version="0.0.8",
+    version="0.0.9",
     description="Plugins for MkDocs and Python Markdown",
     long_description=readme(),
     long_description_content_type="text/markdown",
@@ -39,7 +39,14 @@ def readme():
         "neoteroi.projects",
         "neoteroi.projects.gantt",
     ],
-    install_requires=["essentials-openapi[full]", "mkdocs~=1.4.0", "httpx~=0.23.0"],
+    install_requires=[
+        "essentials-openapi",
+        "mkdocs~=1.4.0",
+        "httpx<1",
+        "click~=8.0.3",
+        "Jinja2~=3.0.2",
+        "rich~=12.2.0",
+    ],
     entry_points={
         "mkdocs.plugins": [
             "neoteroi.mkdocsoad = neoteroi.mkdocsoad:MkDocsOpenAPIDocumentationPlugin",