Improve the Gantt extension and add a contributors extension ⭐

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.7] - 2022-10-01
+- Improves the Gantt extension:
+- - now supports multiple periods in the same row
+- - now supports activities using the start date from the previous activity (automatic dates)
+- Adds a contributors plugin (`neoteroi.contribs`) to display contributors'
+  information in each page, obtaining information from the Git repository at
+  build time :star:
+
 ## [0.0.6] - 2022-08-11 :gem:
 - Adds common classes to enable custom extensions reading configuration from:
 - - YAML, JSON, or CSV embedded in the markdown source

README.md

@@ -14,13 +14,14 @@ pip install neoteroi-mkdocs
 
 This package includes the following plugins and extensions:
 
-| Name                                                              | Description                                                |
-| :---------------------------------------------------------------- | :--------------------------------------------------------- |
-| [`mkdocsoad`](https://www.neoteroi.dev/mkdocs-plugins/web/oad/)   | Generates documentation from OpenAPI specification files.  |
-| [`cards`](https://www.neoteroi.dev/mkdocs-plugins/cards/)         | Component to display cards.                                |
-| [`timeline`](https://www.neoteroi.dev/mkdocs-plugins/timeline/)   | Component to display chronological information with style. |
-| [`gantt`](https://www.neoteroi.dev/mkdocs-plugins/gantt/)         | Component to display Gantt diagrams.                       |
-| [`spantable`](https://www.neoteroi.dev/mkdocs-plugins/spantable/) | Tables supporting colspan and rowspan.                     |
+| Name                                                              | Description                                                               |
+| :---------------------------------------------------------------- | :------------------------------------------------------------------------ |
+| [`mkdocsoad`](https://www.neoteroi.dev/mkdocs-plugins/web/oad/)   | Generates documentation from OpenAPI specification files.                 |
+| [`cards`](https://www.neoteroi.dev/mkdocs-plugins/cards/)         | Component to display cards.                                               |
+| [`timeline`](https://www.neoteroi.dev/mkdocs-plugins/timeline/)   | Component to display chronological information with style.                |
+| [`gantt`](https://www.neoteroi.dev/mkdocs-plugins/gantt/)         | Component to display Gantt diagrams.                                      |
+| [`spantable`](https://www.neoteroi.dev/mkdocs-plugins/spantable/) | Tables supporting colspan and rowspan.                                    |
+| [`contribs`](https://www.neoteroi.dev/mkdocs-plugins/contribs/)   | MkDocs plugin to display last commit time and contributors for each file. |
 
 ## Documentation
 Refer to the [documentation site](https://www.neoteroi.dev/mkdocs-plugins/). :rocket:

neoteroi/contribs/domain.py

@@ -0,0 +1,23 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class Contributor:
+    name: str
+    email: str
+    count: int = -1
+    image: Optional[str] = None
+
+
+class ContributionsReader(ABC):
+    @abstractmethod
+    def get_contributors(self, file_path: Path) -> List[Contributor]:
+        """Obtains the list of contributors for a file with the given path."""
+
+    @abstractmethod
+    def get_last_commit_date(self, file_path: Path) -> datetime:
+        """Reads the last commit date of a file."""

neoteroi/contribs/git.py

@@ -0,0 +1,46 @@
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Iterable, List, Tuple
+
+from dateutil.parser import parse as parse_date
+
+from neoteroi.contribs.domain import ContributionsReader, Contributor
+from neoteroi.markdown.commands import Command
+
+
+class GitContributionsReader(ContributionsReader):
+
+    _name_email_rx = re.compile(r"(?P<name>[\w\s]+)\s<(?P<email>[^\>]+)>")
+
+    def _parse_name_and_email(self, name_and_email) -> Tuple[str, str]:
+        match = self._name_email_rx.search(name_and_email)
+        if match:
+            name = match.groupdict()["name"]
+            email = match.groupdict()["email"]
+        else:
+            name, email = ""
+        return name, email
+
+    def parse_committers(self, output: str) -> Iterable[Contributor]:
+        for line in output.splitlines():
+            count, name_and_email = line.split("\t")
+            name, email = self._parse_name_and_email(name_and_email)
+            yield Contributor(name, email, int(count))
+
+    def get_contributors(self, file_path: Path) -> List[Contributor]:
+        """
+        Obtains the list of contributors for a file with the given path,
+        using the Git CLI.
+        """
+        command = Command(f'git shortlog --summary --numbered --email "{file_path}"')
+
+        result = command.execute()
+        return list(self.parse_committers(result))
+
+    def get_last_commit_date(self, file_path: Path) -> datetime:
+        """Reads the last commit on a file."""
+        command = Command(f'git log -1 --pretty="format:%ci" "{file_path}"')
+
+        result = command.execute()
+        return parse_date(result)

neoteroi/contribs/html.py

@@ -0,0 +1,85 @@
+"""
+This module contains methods to render the contributions stats.
+"""
+import xml.etree.ElementTree as etree
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List
+from xml.etree.ElementTree import tostring as xml_to_str
+
+from neoteroi.contribs.domain import Contributor
+
+
+def _get_initials(value: str) -> str:
+    return "".join([x[0].upper() for x in value.split(" ")][:2])
+
+
+@dataclass
+class ContribsViewOptions:
+    contributors_label: str
+    last_modified_label: str
+    show_last_modified_time: bool
+    time_format: str
+
+
+def contribution_stats_to_element(
+    contributors: List[Contributor],
+    last_commit_date: datetime,
+    options: ContribsViewOptions,
+) -> etree.Element:
+    element = etree.Element("div", {"class": "nt-contribs"})
+
+    if options.show_last_modified_time:
+        last_modified_time = etree.SubElement(
+            element,
+            "em",
+            {"class": "nt-mod-time"},
+        )
+        if options.last_modified_label:
+            last_modified_time.text = (
+                f"{options.last_modified_label}: "
+                f"{last_commit_date.strftime(options.time_format)}"
+            )
+        else:
+            last_modified_time.text = last_commit_date.strftime(options.time_format)
+
+    contributors_parent = etree.SubElement(element, "div", {"class": "nt-contributors"})
+
+    for i, contributor in enumerate(
+        sorted(contributors, key=lambda item: item.count, reverse=True)
+    ):
+        props = {
+            "class": "nt-contributor",
+            "title": (
+                f"{contributor.name} <{contributor.email}> ({contributor.count})"
+            ),
+        }
+
+        if contributor.image:
+            props.update(
+                {
+                    "class": "nt-contributor image",
+                    "style": ("background-image: " f"url('{contributor.image}')"),
+                }
+            )
+        props["class"] += f" nt-group-{i}"
+        contrib_el = etree.SubElement(contributors_parent, "div", props)
+
+        if not contributor.image:
+            # display initials
+            initials_el = etree.SubElement(contrib_el, "span", {"class": "nt-initials"})
+            initials_el.text = _get_initials(contributor.name)
+        else:
+            etree.SubElement(contrib_el, "span", {"class": "nt-initials"})
+
+    return element
+
+
+def render_contribution_stats(
+    contributors: List[Contributor],
+    last_commit_date: datetime,
+    options: ContribsViewOptions,
+) -> str:
+    return xml_to_str(
+        contribution_stats_to_element(contributors, last_commit_date, options)
+    ).decode("utf8")

neoteroi/contribs/py.typed

@@ -0,0 +1 @@
+

neoteroi/markdown/commands.py

@@ -0,0 +1,52 @@
+import logging
+import subprocess
+
+logger = logging.getLogger("MARKDOWN")
+
+
+class Command:
+    def __init__(self, command: str):
+        self._command = None
+        self.command = command
+
+    @property
+    def command(self):
+        if not self._command:
+            raise TypeError("Missing command")
+        return self._command
+
+    @command.setter
+    def command(self, value):
+        self._command = value
+
+    def execute(self) -> str:
+        logger.debug(f"\nNeoteroi Contrib; executing command:\n  {self.command}\n")
+        p = subprocess.Popen(
+            self.command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        )
+        if p.stdout is None:
+            raise TypeError("Missing subprocess stdout")
+
+        output = p.stdout.read()
+        error_output = p.stderr.read() if p.stderr else None
+
+        try:
+            output = output.decode("utf8")
+        except UnicodeDecodeError:
+            output = output.decode("ISO-8859-1")
+
+        if error_output:
+            raise RuntimeError(
+                f"Process failed with return code: "
+                f"{p.returncode}.\nOutput: {output}"
+            )
+
+        if p.returncode is not None and p.returncode != 0:
+            raise RuntimeError(
+                f"Process failed with return code: "
+                f"{p.returncode}.\nOutput: {output}"
+            )
+
+        if output:
+            logger.debug(f"Neoteroi Contrib; got output:\n  {output}\n")
+        return output