Merge pull request #32 from timvink/add_markdown_tags

Add markdown tags

Author: timvink

README.md

@@ -39,25 +39,29 @@ plugins:
 
 ## Usage
 
+### In supported themes
+
+no supported themes *yet*.
+
 ### In markdown pages
 
-You can use ``{{ git_authors_summary }}`` to insert a summary of the authors of a page. Authors are sorted by their name and have a `mailto:` link with their email.
+You can use the following jinja tags to insert content into your markdown pages:
 
-An example output:
+- ``{{ git_page_authors }}`` a summary of the authors of a page. Output wrapped in `<span class='git-page-authors'>`
+- ``{{ git_site_authors }}`` a summary of all authors of all pages in your site. Output wrapped in `<span class='git-site-authors'>`
+
+For example, adding ``{{ git_page_authors }}`` will insert:
 
 ```html
-<span class='git-authors'><a href='mailto:[email protected]'>Jane Doe</a><a href='mailto:[email protected]'>John Doe</a></span>
+<span class='git-page-authors'><a href='mailto:[email protected]'>Jane Doe</a><a href='mailto:[email protected]'>John Doe</a></span>
 ```
 
 Which renders as:
 
-> [Jane Doe](mailto:#), [John Doe](mailto:#)
-
-### In supported themes
+> [Jane Doe](mailto:[email protected]), [John Doe](mailto:[email protected])
 
-no supported themes *yet*.
 
-### In theme customization
+### In theme customizations
 
 [MkDocs](https://www.mkdocs.org/) offers possibilities to [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme).
 
@@ -71,7 +75,7 @@ As an example, if you use [mkdocs-material](https://github.com/squidfunk/mkdocs-
 {% block disqus %}
     <div class="md-source-date">
     <small>
-        Authors: {{ git_authors_summary }}
+        Authors: {{ git_page_authors }}
     </small>
   </div>
     {% include "partials/integrations/disqus.html" %}
@@ -88,46 +92,53 @@ theme:
 
 ### In theme templates
 
-To add more detailed author information to your theme you can [customize a MkDocs theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme) or even [develop your own](https://www.mkdocs.org/user-guide/custom-themes/). When enabling this plugin, you will have access to the jinja2 variable `git_authors`, which contains a list of authors dicts, like the following example:
+To add more detailed git author information to your theme you can [customize a MkDocs theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme) or even [develop your own](https://www.mkdocs.org/user-guide/custom-themes/). 
+
+When enabling this plugin, you will have access to the jinja2 variable `git_info` which contains as dict with the following structure:
 
 ```python
-[{
+{
+  'page_authors' : [
+    {
     'name' : 'Jane Doe',
     'email' : '[email protected]',
     'last_datetime' : datetime.datetime(),
     'lines' : 200,
     'contribution' : '40.0%'
-},
-{
+  },
+  {
     'name' : 'John Doe',
     'email' : '[email protected]',
     'last_datetime' : datetime.datetime(),
     'lines' : 300,
     'contribution' : '60.0%'
-}]
+  }
+ ],
+ 'site_authors' : # same structure
+}
 ```
 
 #### Example usage in theme development
 
 An example of how to use in your templates:
 
 ```django hljs
-{% if git_authors %}
-  {%- for author in git_authors -%}
+{% if git_info %}
+  {%- for author in git_info.get('page_authors') -%}
     <a href="{{ author.email }}" title="{{ author.name }}">
       {{ author.name }}
     </a>,
   {%- endfor -%}
 {% endif %}
 ```
 
-Alternatively, you could use the simple preformatted ``{{ git_authors_summary }}`` to insert a summary of the authors.
+Alternatively, you could use the simple pre-formatted `{{ git_page_authors }}` 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
+If this option is set to `true` (default: `false`) the contribution of a author is
 printed as a percentage of (source file) lines per author. The output is
 suppressed if there is only *one* author for a page.
 
@@ -136,6 +147,16 @@ Example output:
 * Authors: [John Doe](#) (33.33%), [Jane Doe](#) (66.67%) *(more than one author)*
 * Authors: [John Doe](#) *(one author)*
 
+### `show_line_count`
+
+If this option is set to `true` (default: `false`) the number of lines per author is shown.
+
+### `count_empty_lines`
+
+If this option is set to `true` (default: `false`) empty lines will count towards an authors' contribution.
+
+## Tricks
+
 ### Aggregating Authors
 
 In some repositories authors may have committed with differing name/email combinations.

mkdocs_git_authors_plugin/git/author.py

@@ -33,12 +33,12 @@ def add_lines(self, page: Page, commit: Commit, lines: int = 1):
         """
         path = page.path()
         entry = self.page(path, page)
-        entry['lines'] += lines
-        current_dt = entry.get('datetime')
+        entry["lines"] += lines
+        current_dt = entry.get("datetime")
         commit_dt = commit.datetime()
         if not current_dt or commit_dt > current_dt:
-            entry['datetime'] = commit_dt
-            entry['datetime_str'] = commit.datetime(str)
+            entry["datetime"] = commit_dt
+            entry["datetime_str"] = commit.datetime(str)
 
     def contribution(self, path=None, _type=float):
         """
@@ -59,15 +59,13 @@ def contribution(self, path=None, _type=float):
         """
         lines = self.lines(path)
         total_lines = (
-            self.page(path)['page'].total_lines()
-            if path
-            else self.repo().total_lines()
+            self.page(path)["page"].total_lines() if path else self.repo().total_lines()
         )
         result = lines / total_lines
         if _type == float:
             return result
         else:
-            return str(round(result * 100, 2)) + '%'
+            return str(round(result * 100, 2)) + "%"
 
     def datetime(self, path, fmt=str):
         """
@@ -81,7 +79,7 @@ def datetime(self, path, fmt=str):
             a formatted string (fmt=str)
             or a datetime.datetime object with tzinfo
         """
-        key = 'datetime_str' if fmt == str else 'datetime'
+        key = "datetime_str" if fmt == str else "datetime"
         return self.page(path).get(key)
 
     def email(self):
@@ -107,11 +105,9 @@ def lines(self, path=None):
             or on the given page.
         """
         if path:
-            return self.page(path)['lines']
+            return self.page(path)["lines"]
         else:
-            return sum([
-                v['lines'] for v in self._pages.values()
-            ])
+            return sum([v["lines"] for v in self._pages.values()])
 
     def name(self):
         """
@@ -149,8 +145,8 @@ def page(self, path, page=None):
         """
         if not self._pages.get(path):
             self._pages[path] = {
-                'page': page or self.repo().page(path),
-                'lines': 0
+                "page": page or self.repo().page(path),
+                "lines": 0
                 # datetime and datetime_str will be populated later
             }
         return self._pages[path]

mkdocs_git_authors_plugin/git/command.py

@@ -1,9 +1,11 @@
 import subprocess
 
+
 class GitCommandError(Exception):
     """
     Exception thrown by a GitCommand.
     """
+
     pass
 
 
@@ -53,30 +55,29 @@ def run(self):
                 Note: usually the result will be used through the methods.
         """
 
-        args = ['git']
+        args = ["git"]
         args.append(self._command)
         args.extend(self._args)
         p = subprocess.run(
             args,
             # encoding='utf8', # Uncomment after dropping support for python 3.5
             stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE
+            stderr=subprocess.PIPE,
         )
         try:
             p.check_returncode()
         except subprocess.CalledProcessError:
-            msg = ['GitCommand error:']
-            msg.append('Command "%s" failed' % ' '.join(args))
-            msg.append('Return code: %s' % p.returncode)
-            msg.append('Output:')
+            msg = ["GitCommand error:"]
+            msg.append('Command "%s" failed' % " ".join(args))
+            msg.append("Return code: %s" % p.returncode)
+            msg.append("Output:")
             msg.append(p.stdout.decode("utf-8"))
-            msg.append('Error messages:')
+            msg.append("Error messages:")
             msg.append(p.stderr.decode("utf-8"))
-            raise GitCommandError('\n'.join(msg))
-        
-        self._stdout = p.stdout.decode("utf-8").strip('\'\n').split('\n')
-        self._stderr = p.stderr.decode("utf-8").strip('\'\n').split('\n')
-        
+            raise GitCommandError("\n".join(msg))
+
+        self._stdout = p.stdout.decode("utf-8").strip("'\n").split("\n")
+        self._stderr = p.stderr.decode("utf-8").strip("'\n").split("\n")
 
         self._completed = True
         return int(str(p.returncode))
@@ -109,7 +110,7 @@ def stderr(self):
             string list
         """
         if not self._completed:
-            raise GitCommandError('Trying to read from uncompleted GitCommand')
+            raise GitCommandError("Trying to read from uncompleted GitCommand")
         return self._stderr
 
     def stdout(self):
@@ -122,5 +123,5 @@ def stdout(self):
             string list
         """
         if not self._completed:
-            raise GitCommandError('Trying to read from uncompleted GitCommand')
+            raise GitCommandError("Trying to read from uncompleted GitCommand")
         return self._stdout

mkdocs_git_authors_plugin/git/commit.py

@@ -2,6 +2,7 @@
 from .repo import AbstractRepoObject, Repo
 from .. import util
 
+
 class Commit(AbstractRepoObject):
     """
     Information about a single commit.
@@ -20,7 +21,7 @@ def __init__(
         author_email: str,
         author_time: str,
         author_tz: str,
-        summary: str
+        summary: str,
     ):
         """Initialize a commit from its SHA.
 
@@ -33,15 +34,12 @@ def __init__(
 
         super().__init__(repo)
 
-        # Replace <> 
+        # Replace <>
         # from '<[email protected]>'
         # to   '[email protected]'
-        author_email = re.sub(r"\<|\>","", author_email)
-         
-        self._author = self.repo().author(
-            author_name,
-            author_email
-        )
+        author_email = re.sub(r"\<|\>", "", author_email)
+
+        self._author = self.repo().author(author_name, author_email)
         self._datetime = util.commit_datetime(author_time, author_tz)
         self._datetime_string = util.commit_datetime_string(self._datetime)
         self._summary = summary