fix: Resolve paths relative to srcdir or current document

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

Author: SilverRainZ

docs/index.rst

@@ -30,12 +30,10 @@ Introduction
 Get the Sphinx document update information from Git repository.
 
 This extension provides a :rst:dir:`recentupdate` directive that displays
-recent document update information read from a Git_ repository. It also
+recent document update information read from a Git repository. It also
 integrates with :external+render:doc:`sphinxnotes-render <index>` by
 providing an extra context for use in render templates.
 
-.. _Git: https://git-scm.com/
-
 .. INTRODUCTION END
 
 Getting Started

docs/usage.rst

@@ -28,8 +28,9 @@ The ``recentupdate`` Directive
    .. rst:directive:option:: paths
       :type: lines of str
 
-      Git pathspecs (:manpage:`gitglossary(7)`) to filter file changes,
-      one per line. Defaults to ``.``.
+      Paths to filter file changes, one per line.
+      Paths starting with ``/`` are relative to the source directory;
+      other paths are relative to the current document's directory.
 
       See also :example:`Recent Updates of Custom Path`.
 
@@ -137,7 +138,7 @@ Examples
    Recent changes of the :doc:`changelog`:
 
    .. recentupdate::
-      :paths: docs/changelog.rst
+      :paths: /changelog.rst
 
       {% for r in revisions %}
       ``{{ r.date.strftime('%Y-%m-%d') }}`` — {{ r.message[0] }}

src/sphinxnotes/recentupdate/__init__.py

@@ -201,6 +201,30 @@ def path2doc(repo: Repo, env: BuildEnvironment, blob_path: str) -> str | None:
     return '/' + docname if (docname and not path.isabs(docname)) else None
 
 
+def _resolve_paths(
+    repo: Repo,
+    env: BuildEnvironment,
+    docname: str,
+    paths: list[str],
+) -> list[str]:
+    """Resolve user-supplied paths to repo-relative paths.
+
+    - Paths starting with '/' are relative to srcdir.
+    - Paths starting with './' or without prefix are relative to the current
+      document's directory.
+    """
+    resolved = []
+    for p in paths:
+        if p.startswith('/'):
+            abspath = path.join(env.srcdir, p[1:])
+        else:
+            docdir = path.dirname(env.doc2path(docname))
+            abspath = path.join(docdir, p)
+        rel = path.relpath(abspath, repo.working_dir)
+        resolved.append(rel)
+    return resolved
+
+
 def collect_revisions(
     repo: Repo,
     env: BuildEnvironment,
@@ -255,6 +279,7 @@ def current_context(self) -> dict:
             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()]
+            paths = _resolve_paths(repo, self.env, self.env.docname, paths)
         else:
             paths = []
 
@@ -288,6 +313,8 @@ def generate(
         if self_only:
             docpath = req.env.doc2path(req.env.docname)
             paths = [path.relpath(docpath, repo.working_dir)]
+        else:
+            paths = _resolve_paths(repo, req.env, req.env.docname, paths)
 
         return collect_revisions(repo, req.env, count, paths, group_by)
 

tests/test_resolve_paths.py

@@ -0,0 +1,62 @@
+import unittest
+from unittest.mock import MagicMock
+
+from sphinxnotes.recentupdate import _resolve_paths
+
+
+def _make_repo(working_dir='/srv/repo'):
+    repo = MagicMock()
+    repo.working_dir = working_dir
+    return repo
+
+
+def _make_env(srcdir='/srv/repo/docs'):
+    env = MagicMock()
+    env.srcdir = srcdir
+
+    def doc2path(docname):
+        return f'{srcdir}/{docname}.rst'
+
+    env.doc2path = doc2path
+    return env
+
+
+class TestResolvePaths(unittest.TestCase):
+    def test_absolute_path_resolves_relative_to_srcdir(self):
+        """Paths starting with '/' are relative to srcdir."""
+        repo = _make_repo('/srv/repo')
+        env = _make_env('/srv/repo/docs')
+        result = _resolve_paths(repo, env, 'index', ['/subdir/page'])
+        self.assertEqual(result, ['docs/subdir/page'])
+
+    def test_relative_path_resolves_relative_to_doc_dir(self):
+        """Paths without prefix are relative to current document's directory."""
+        repo = _make_repo('/srv/repo')
+        env = _make_env('/srv/repo/docs')
+        result = _resolve_paths(repo, env, 'subdir/index', ['other'])
+        self.assertEqual(result, ['docs/subdir/other'])
+
+    def test_dot_slash_path_resolves_relative_to_doc_dir(self):
+        """Paths starting with './' are relative to current document's directory."""
+        repo = _make_repo('/srv/repo')
+        env = _make_env('/srv/repo/docs')
+        result = _resolve_paths(repo, env, 'subdir/index', ['./other'])
+        self.assertEqual(result, ['docs/subdir/other'])
+
+    def test_root_doc_relative_path(self):
+        """Relative path from root document resolves correctly."""
+        repo = _make_repo('/srv/repo')
+        env = _make_env('/srv/repo/docs')
+        result = _resolve_paths(repo, env, 'index', ['page'])
+        self.assertEqual(result, ['docs/page'])
+
+    def test_empty_paths(self):
+        """Empty paths list returns empty list."""
+        repo = _make_repo('/srv/repo')
+        env = _make_env('/srv/repo/docs')
+        result = _resolve_paths(repo, env, 'index', [])
+        self.assertEqual(result, [])
+
+
+if __name__ == '__main__':
+    unittest.main()