feat: Add recentupdate directive using BaseContextDirective

Co-authored-by: MiMoCode <mimo@xiaomi.com>

Author: SilverRainZ

src/sphinxnotes/recentupdate/__init__.py

@@ -15,16 +15,22 @@
 from collections import OrderedDict
 from os import path
 from itertools import islice
+from textwrap import dedent
 
 from git import Repo
 
+from docutils.parsers.rst import directives
+
 from sphinx.util import logging
 from sphinx.config import ENUM
 
 from sphinxnotes.render import (
     extra_context,
     ExtraContext,
     ExtraContextRequest,
+    BaseContextDirective,
+    Phase,
+    Template,
 )
 
 from . import meta
@@ -156,7 +162,7 @@ def get_git_revisions(
             # :T: change in the type of the file
             # :U: file is unmerged (you must complete the merge before it can be committed)
             # :X: "unknown" change type (most probably a bug, please report it)
-            status_maps = {'M': m, 'A': a, 'D': d }
+            status_maps = {'M': m, 'A': a, 'D': d}
 
             # Use git diff --name-status with pathspecs for native pathspec matching
             name_status = repo.git.diff(
@@ -190,11 +196,98 @@ def get_git_revisions(
 
 
 def path2doc(repo: Repo, env: BuildEnvironment, blob_path: str) -> str | None:
-    """Convert a git repo-relative blob path to a Sphinx document name. """
+    """Convert a git repo-relative blob path to a Sphinx document name."""
     docname = env.path2doc(path.join(repo.working_dir, blob_path))
     return docname if (docname and not path.isabs(docname)) else None
 
 
+def collect_revisions(
+    repo: Repo,
+    env: BuildEnvironment,
+    count: int,
+    paths: list[str],
+    group_by: str = '',
+) -> list[Revision]:
+    """Collect recent revisions from git, optionally grouped by time period."""
+    count = count or env.config.recentupdate_count
+    group_by = group_by or env.config.recentupdate_group_by
+
+    git_revs = get_git_revisions(repo, env, paths)
+
+    if group_by:
+        groups = OrderedDict()
+        for rev in git_revs:
+            group_revisions(groups, rev, group_by)
+            if len(groups) >= count:
+                break
+        revs = compact_groups(groups)
+    else:
+        revs = list(islice(git_revs, count))
+    logger.info(
+        f'[recentupdate] Expect {count} revisions, finally get {len(revs)}, group by {group_by}'
+    )
+
+    return revs
+
+
+DEFAULT_TEMPLATE = dedent("""\
+    {% for r in revisions %}
+    {{ r.date.strftime('%Y-%m-%d') }}
+      :Author: {{ r.author }}
+      :Message: {{ r.message | join(', ') }}
+
+      {% if r.changed_docs -%}
+      - Modified {{ r.changed_docs | roles("doc") | join(", ") }}
+      {% endif %}
+      {% if r.added_docs -%}
+      - Added {{ r.added_docs | roles("doc") | join(", ") }}
+      {% endif %}
+      {% if r.removed_docs -%}
+      - Deleted {{ r.removed_docs | join(", ") }}
+      {% endif %}
+    {% endfor %}
+    """)
+
+
+class RecentUpdateDirective(BaseContextDirective):
+    """Directive for displaying recent document updates."""
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    option_spec = {
+        'self': directives.flag,
+        'paths': directives.unchanged,
+    }
+
+    def current_context(self) -> dict:
+        repo = RecentUpdateExtraContext.repo
+
+        count = (
+            int(self.arguments[0])
+            if self.arguments
+            else self.env.config.recentupdate_count
+        )
+
+        current_doc = 'self' in self.options
+        if current_doc:
+            docpath = self.env.doc2path(self.env.docname)
+            paths = [path.relpath(docpath, repo.working_dir)]
+        elif 'paths' in self.options:
+            paths = [p.strip() for p in self.options['paths'].splitlines() if p.strip()]
+        else:
+            paths = ['.']
+
+        revs = collect_revisions(repo, self.env, count, paths)
+        return {'revisions': revs}
+
+    def current_template(self) -> Template:
+        text = '\n'.join(self.content) if self.has_content and self.content else ''
+        if not text.strip():
+            text = self.env.config.recentupdate_template
+        return Template(text, phase=Phase.Parsing)
+
+
 @extra_context('recentupdate')
 class RecentUpdateExtraContext(ExtraContext):
     """Extra context providing recent document revisions from Git."""
@@ -206,34 +299,18 @@ def generate(
         self,
         req: ExtraContextRequest,
         count: int = 0,
-        paths: list[str] = ['.', ],
+        paths: list[str] = [
+            '.',
+        ],
         current_doc: bool = False,
         group_by: str = '',
     ) -> Any:
-        count = count or req.env.config.recentupdate_count
-        group_by = group_by or req.env.config.recentupdate_group_by
-
         if current_doc:
             docpath = req.env.doc2path(req.env.docname)
             repo_path = path.relpath(docpath, self.repo.working_dir)
             paths = [repo_path]
 
-        git_revs = get_git_revisions(self.repo, req.env, paths)
-
-        if group_by:
-            groups = OrderedDict()
-            for rev in git_revs:
-                group_revisions(groups, rev, group_by)
-                if len(groups) >= count:
-                    break
-            revs = compact_groups(groups)
-        else:
-            revs = list(islice(git_revs, count))
-        logger.info(
-            f'[recentupdate] Expect {count} revisions, finally get {len(revs)}, group by {group_by}'
-        )
-
-        return revs
+        return collect_revisions(self.repo, req.env, count, paths, group_by)
 
 
 def setup(app: Sphinx):
@@ -243,10 +320,13 @@ def setup(app: Sphinx):
 
     app.setup_extension('sphinxnotes.render')
 
+    app.add_directive('recentupdate', RecentUpdateDirective)
+
     app.add_config_value(
         'recentupdate_exclude_commit', ['skip-recentupdate'], 'env', types=list[str]
     )
     app.add_config_value('recentupdate_count', 10, 'env', types=int)
+    app.add_config_value('recentupdate_template', DEFAULT_TEMPLATE, 'env', types=str)
     app.add_config_value(
         'recentupdate_group_by', None, 'env', types=ENUM(None, 'day', 'month', 'year')
     )