Merge pull request #6 from uliska/show-contribution-new

Show contribution new

Author: timvink

README.md

@@ -86,6 +86,19 @@ An example of how to use in your templates:
 
 Alternatively, you could use the simple preformatted ``{{ git_authors_summary }}`` to insert a summary of the authors.
 
+## Options
+
+### `show_contribution`
+
+If this option is set to `true` (default: `false`) The contribution to a page is
+printed as a percentage of (source file) lines per author. The output is
+suppressed if there is only *one* author for a page.
+
+Example output:
+
+* Authors: [John Doe](#) (33.33%), [Jane Doe](#) (66.67%) *(more than one author)*
+* Authors: [John Doe](#) *(one author)*
+
 ### Aggregating Authors
 
 In some repositories authors may have committed with differing name/email combinations.

mkdocs_git_authors_plugin/plugin.py

@@ -1,8 +1,13 @@
 import re
+from mkdocs.config import config_options
 from mkdocs.plugins import BasePlugin
 from .util import Util
 
 class GitAuthorsPlugin(BasePlugin):
+    config_scheme = (
+        ('show_contribution', config_options.Type(bool, default=False)),
+    )
+
     def __init__(self):
         self.util = Util()
 
@@ -35,7 +40,7 @@ def on_page_markdown(self, markdown, page, config, files):
         authors = self.util.get_authors(
             path = page.file.abs_src_path
         )
-        authors_summary = self.util.summarize(authors)
+        authors_summary = self.util.summarize(authors, self.config)
 
         return re.sub(pattern,
                       authors_summary,
@@ -65,7 +70,7 @@ def on_page_context(self, context, page, **kwargs):
         authors = self.util.get_authors(
             path = page.file.abs_src_path
         )
-        authors_summary = self.util.summarize(authors)
+        authors_summary = self.util.summarize(authors, self.config)
 
         context['git_authors'] = authors
         context['git_authors_summary'] = authors_summary

mkdocs_git_authors_plugin/util.py

@@ -27,7 +27,7 @@ def get_authors(self, path):
 
         if authors:
             return authors
-        
+
         try:
             blame = self.repo.blame('HEAD',path)
         except:
@@ -82,7 +82,7 @@ def _format_perc(n, decimals = 2):
         return str(round(n * 100, decimals)) + '%'
 
     @staticmethod
-    def summarize(authors):
+    def summarize(authors, config):
         """
         Summarized list of authors to a HTML string
 
@@ -93,6 +93,21 @@ def summarize(authors):
             str: HTML text with authors
         """
 
-        authors_summary = ["<a href='mailto:%s'>%s</a>" % (x['email'] ,x['name']) for x in authors]
+        def format_author(author):
+            contrib = (
+                ' (%s)' % author['contribution']
+                if (
+                    config['show_contribution']
+                    and len(authors) > 1
+                )
+                else ''
+            )
+            return "<a href='mailto:%s'>%s</a>%s" % (
+                author['email'],
+                author['name'],
+                contrib
+            )
+
+        authors_summary = [format_author(author) for author in authors]
         authors_summary = ', '.join(authors_summary)
         return "<span class='git-authors'>" + authors_summary + "</span>"

tests/test_util.py

@@ -3,7 +3,7 @@
 from git import Actor, Repo
 
 def test_empty_file(tmp_path):
-    
+
     # Create empty file
     file_name = os.path.join(tmp_path, 'new-file')
     open(file_name, 'a').close()
@@ -13,24 +13,24 @@ def test_empty_file(tmp_path):
     instance = util.Util(tmp_path)
     authors = instance.get_authors(path = file_name)
     assert authors == []
-    
+
     # Get authors of empty, committed file
     r.index.add([file_name])
     author = Actor('Tim', '[email protected]')
     r.index.commit("initial commit", author = author)
     authors = instance.get_authors(path = file_name)
     assert authors == []
-    
+
 def test_retrieve_authors(tmp_path):
     """
     Builds a fake git project with some commits.
-    
+
     pytest offers a `tmp_path`. You can reproduce locally with
     >>> import tempfile
     >>> from pathlib import Path
     >>> tmp_path = Path(tempfile.gettempdir()) / 'pytest-retrieve-authors'
     >>> os.mkdir(tmp_path)
-    
+
     Args:
         tmp_path (PosixPath): Directory of a tempdir
     """
@@ -45,52 +45,52 @@ def test_retrieve_authors(tmp_path):
     r.index.add([file_name])
     author = Actor('Tim', '[email protected]')
     r.index.commit("initial commit", author = author)
-    
+
     instance = util.Util(tmp_path)
     authors = instance.get_authors(path = file_name)
     # We don't want to test datetime
     authors[0]['last_datetime'] = None
-     
+
     assert authors == [{
                     'name' : "Tim",
                     'email' : "[email protected]",
                     'last_datetime' : None,
                     'lines' : 1,
                     'contribution' : '100.0%'
                 }]
-    
-    # Now add a line to the file 
+
+    # Now add a line to the file
     # From a second author with same email
     with open(file_name, 'a+') as the_file:
         the_file.write('World\n')
     r.index.add([file_name])
     author = Actor('Tim2', '[email protected]')
-    r.index.commit("another commit", author = author) 
-    
+    r.index.commit("another commit", author = author)
+
     instance = util.Util(tmp_path)
     authors = instance.get_authors(path = file_name)
-    authors[0]['last_datetime'] = None 
-    
+    authors[0]['last_datetime'] = None
+
     assert authors == [{
                     'name' : "Tim",
                     'email' : "[email protected]",
                     'last_datetime' : None,
                     'lines' : 2,
                     'contribution' : '100.0%'
                 }]
-    
+
     # Then a third commit from a new author
     with open(file_name, 'a+') as the_file:
         the_file.write('A new line\n')
     r.index.add([file_name])
     author = Actor('John', '[email protected]')
-    r.index.commit("third commit", author = author)  
-   
-    instance = util.Util(tmp_path) 
+    r.index.commit("third commit", author = author)
+
+    instance = util.Util(tmp_path)
     authors = instance.get_authors(path = file_name)
-    authors[0]['last_datetime'] = None 
-    authors[1]['last_datetime'] = None 
-    
+    authors[0]['last_datetime'] = None
+    authors[1]['last_datetime'] = None
+
     assert authors == [{
                     'name' : "John",
                     'email' : "[email protected]",
@@ -103,15 +103,33 @@ def test_retrieve_authors(tmp_path):
                     'last_datetime' : None,
                     'lines' : 2,
                     'contribution' : '66.67%'
-                }] 
+                }]
 
 def test_summarize_authors():
-    
+
     authors = [
         {'name' : 'Tim',
-         'email' : '[email protected]'
+         'email' : '[email protected]',
+         'contribution' : '64.23%'
         }
     ]
-    
-    summary = util.Util().summarize(authors)
-    assert summary == "<span class='git-authors'><a href='mailto:[email protected]'>Tim</a></span>"
+
+    # Default case: don't show contribution
+    config = { 'show_contribution' : False }
+    summary = util.Util().summarize(authors, config)
+    assert summary == "<span class='git-authors'><a href='mailto:[email protected]'>Tim</a></span>"
+
+    # Do show contribution, but hide it because there's only one author
+    config = { 'show_contribution' : True }
+    summary = util.Util().summarize(authors, config)
+    assert summary == "<span class='git-authors'><a href='mailto:[email protected]'>Tim</a></span>"
+
+    # Add another author
+    authors.append({
+        'name' : 'Tom',
+        'email' : '[email protected]',
+        'contribution' : '35.77%'
+    })
+    # Now contribution is displayed
+    summary = util.Util().summarize(authors, config)
+    assert summary == "<span class='git-authors'><a href='mailto:[email protected]'>Tim</a> (64.23%), <a href='mailto:[email protected]'>Tom</a> (35.77%)</span>"