diff --git a/hooks.py b/hooks.py index f3612084..df8e1085 100644 --- a/hooks.py +++ b/hooks.py @@ -13,7 +13,7 @@ "community/code-of-conduct.md": "CODE_OF_CONDUCT.md", } -# 每个文件只查一次 git,27 个页面也只多 27 次子进程调用。 +# 每轮构建中每个文件只查一次 git,27 个页面也只多 27 次子进程调用。 _last_commit_cache = {} @@ -113,6 +113,9 @@ def on_page_context(context, page, config, **kwargs): # 在 MkDocs 构建开始前,将根目录下的社区文件复制到文档站页面。 # (名称必须为 on_pre_build) def on_pre_build(config, **kwargs): + # mkdocs serve 会复用 hook 模块,下一轮构建应重新读取提交历史。 + _last_commit_cache.clear() + docs_dir = config["docs_dir"] repo_root = Path(__file__).resolve().parent diff --git a/tests/test_hooks.py b/tests/test_hooks.py index 4ef52ef9..7438195c 100644 --- a/tests/test_hooks.py +++ b/tests/test_hooks.py @@ -18,10 +18,11 @@ 9. 空文档目录的统计结果为 0。 10. 根目录行为准则构建时生成社区文档页。 11. 行为准则生成页的编辑链接指向根目录源文件。 + 12. 页面提交信息在同轮构建中复用缓存,在下一轮构建时刷新。 预期运行效果: 逐项输出测试名称,通过时每项末尾显示 ok,最后显示: - Ran 21 tests in ...s + Ran ... tests in ...s OK 实际耗时因环境而异;若显示 FAILED 或 ERROR,应检查后面的错误信息。 @@ -208,23 +209,73 @@ def setUp(self): (self.root / "docs" / "adv").mkdir(parents=True) (self.root / "docs" / "adv" / "find_author.md").write_text("# 页\n", encoding="utf-8") (self.root / "CONTRIBUTING.md").write_text("# 贡献指南\n", encoding="utf-8") + (self.root / "CODE_OF_CONDUCT.md").write_text("# 行为准则\n", encoding="utf-8") self._git("init", "-q") - self._git("add", "docs/adv/find_author.md", "CONTRIBUTING.md") - self._git("commit", "-q", "-m", "docs: 第一版", name="张三") + self._git("add", "docs/adv/find_author.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md") + self._git("commit", "-q", "-m", "docs: 第一版", name="张三", + date="2020-01-01T12:00:00+0000") hooks._last_commit_cache.clear() def tearDown(self): shutil.rmtree(self.root, ignore_errors=True) - def _git(self, *args, name="张三", email="tester@example.com"): + def _git(self, *args, name="张三", email="tester@example.com", date=None): + env = os.environ.copy() + if date: + env.update(GIT_AUTHOR_DATE=date, GIT_COMMITTER_DATE=date) subprocess.run( ["git", "-c", "user.name=" + name, "-c", "user.email=" + email, *args], - cwd=str(self.root), check=True, capture_output=True, text=True, + cwd=str(self.root), check=True, capture_output=True, text=True, env=env, ) def _page(self, src_uri): return SimpleNamespace(file=SimpleNamespace(src_uri=src_uri)) + def _start_build(self): + with patch.object(hooks, "__file__", str(self.root / "hooks.py")), \ + redirect_stdout(io.StringIO()): + hooks.on_pre_build({"docs_dir": str(self.root / "docs")}) + + def test_last_commit_cache_is_reused_within_build(self): + self._start_build() + with patch.object(hooks.subprocess, "run", wraps=subprocess.run) as git_run: + first = hooks.last_commit("docs/adv/find_author.md", self.root) + second = hooks.last_commit("docs/adv/find_author.md", self.root) + self.assertEqual(first, second) + self.assertEqual(first[2], "张三") + git_run.assert_called_once() + + def test_new_build_refreshes_cached_page_commit(self): + self._start_build() + first = hooks.last_commit("docs/adv/find_author.md", self.root) + self.assertEqual(first[1:], ("2020-01-01", "张三")) + + (self.root / "docs" / "adv" / "find_author.md").write_text( + "# 第二版\n", encoding="utf-8", + ) + self._git("commit", "-q", "-am", "docs: 第二版", name="李四", + date="2020-01-02T12:00:00+0000") + + self._start_build() + second = hooks.last_commit("docs/adv/find_author.md", self.root) + self.assertEqual(second[1:], ("2020-01-02", "李四")) + self.assertNotEqual(first[0], second[0]) + line = hooks.provenance_line(self._page("adv/find_author.md"), self.root) + self.assertIn("2020-01-02 · 李四", line) + self.assertIn(second[0], line) + + def test_new_build_rechecks_cached_uncommitted_page(self): + (self.root / "docs" / "new.md").write_text("# 新页\n", encoding="utf-8") + self._start_build() + self.assertEqual(hooks.provenance_line(self._page("new.md"), self.root), "") + + self._git("add", "docs/new.md") + self._git("commit", "-q", "-m", "docs: 新页", name="李四", + date="2020-01-02T12:00:00+0000") + self._start_build() + line = hooks.provenance_line(self._page("new.md"), self.root) + self.assertIn("2020-01-02 · 李四", line) + def test_last_commit_reads_hash_date_and_author(self): info = hooks.last_commit("docs/adv/find_author.md", self.root) self.assertEqual(len(info), 3)