diff --git a/.gitignore b/.gitignore index c3717c55..403a7da6 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ tests/_tmp/ # mkdocs 构建产物(本地 serve/build 生成) site/ docs/CONTRIBUTING.md +docs/community/code-of-conduct.md # 脚本与工作流产物 commit_stats.csv diff --git a/hooks.py b/hooks.py index 05680e78..f3612084 100644 --- a/hooks.py +++ b/hooks.py @@ -7,6 +7,12 @@ REPO_ROOT = Path(__file__).resolve().parent +# 仓库根目录中的社区文件 -> 构建时生成的文档站页面。 +GENERATED_DOC_FILES = { + "CONTRIBUTING.md": "CONTRIBUTING.md", + "community/code-of-conduct.md": "CODE_OF_CONDUCT.md", +} + # 每个文件只查一次 git,27 个页面也只多 27 次子进程调用。 _last_commit_cache = {} @@ -50,8 +56,8 @@ def last_commit(source_path, repo_root=None): def provenance_line(page, repo_root=None, repo_url=None): """生成「本页最近一次修改」那一行;取不到信息时返回空字符串。""" src_uri = page.file.src_uri - # docs/CONTRIBUTING.md 是构建前从仓库根目录复制来的,历史要查根目录那个文件。 - source_path = "CONTRIBUTING.md" if src_uri == "CONTRIBUTING.md" else "docs/" + src_uri + # 生成页的历史要查仓库根目录中的源文件,而不是 docs/ 下的构建副本。 + source_path = GENERATED_DOC_FILES.get(src_uri, "docs/" + src_uri) root = Path(repo_root) if repo_root else REPO_ROOT if is_shallow_clone(root): @@ -91,37 +97,42 @@ def on_config(config, **kwargs): config.copyright = copyright_text.replace("{year}", year) -# CONTRIBUTING.md 是从仓库根目录复制的,编辑按钮也应指回根目录源文件。 +# 生成页是从仓库根目录复制的,编辑按钮也应指回根目录源文件。 def on_page_context(context, page, config, **kwargs): - if page.file.src_uri != "CONTRIBUTING.md" or not page.edit_url: + source_name = GENERATED_DOC_FILES.get(page.file.src_uri) + if not source_name or not page.edit_url: return context docs_name = Path(config["docs_dir"]).name - generated_suffix = f"/{docs_name}/CONTRIBUTING.md" + generated_suffix = f"/{docs_name}/{page.file.src_uri}" if page.edit_url.endswith(generated_suffix): - page.edit_url = page.edit_url[: -len(generated_suffix)] + "/CONTRIBUTING.md" + page.edit_url = page.edit_url[: -len(generated_suffix)] + "/" + source_name return context -# 在 MkDocs 构建开始前,将根目录下的 CONTRIBUTING.md -# 拷贝到 docs 目录下,确保文档站点能够引用到它。 +# 在 MkDocs 构建开始前,将根目录下的社区文件复制到文档站页面。 # (名称必须为 on_pre_build) def on_pre_build(config, **kwargs): - # 源文件:项目根目录下的文件 - src_file = os.path.join(os.path.dirname(__file__), 'CONTRIBUTING.md') - # 目标文件:MkDocs 配置中的 docs_dir docs_dir = config["docs_dir"] - os.makedirs(docs_dir, exist_ok=True) - dest_file = os.path.join(docs_dir, 'CONTRIBUTING.md') - - # 执行拷贝 - if os.path.exists(src_file): - shutil.copy2(src_file, dest_file) - print("Successfully copied CONTRIBUTING.md to docs/CONTRIBUTING.md") - else: - logging.getLogger(__name__).warning( - "Source file not found: %s; contribution guide was not copied", src_file - ) + repo_root = Path(__file__).resolve().parent + + for destination, source_name in GENERATED_DOC_FILES.items(): + src_file = repo_root / source_name + dest_file = Path(docs_dir) / destination + dest_file.parent.mkdir(parents=True, exist_ok=True) + + if src_file.exists(): + shutil.copy2(src_file, dest_file) + print( + "Successfully copied %s to %s" + % (source_name, dest_file.relative_to(repo_root)) + ) + else: + logging.getLogger(__name__).warning( + "Source file not found: %s; %s was not copied", + src_file, + destination, + ) # 构建完成后,输出文档构建统计信息 diff --git a/mkdocs.yml b/mkdocs.yml index 271a5da8..7513c542 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,6 +82,7 @@ nav: # 以下为补充收录的文档页面 - 贡献相关: + - 社区行为准则: 'community/code-of-conduct.md' - 基于浏览器的贡献指南: 'codespace.md' - 注册 Github 账号: 'dev/sign_up.md' - 使用 VScode 推送代码: 'dev/vscode_push.md' diff --git a/tests/test_docs_links.py b/tests/test_docs_links.py index 8a908140..5cb85c38 100644 --- a/tests/test_docs_links.py +++ b/tests/test_docs_links.py @@ -10,11 +10,14 @@ MARKDOWN_LINK = re.compile(r"!?\[[^\]]*\]\(\s*(<[^>]+>|[^\s)]+)") FENCE = re.compile(r"^\s*(`{3,}|~{3,})") -# MkDocs copies the root contribution guide into docs before building. +# MkDocs copies root community files into docs before building. GENERATED_DOC_FILES = { (REPO_ROOT / "docs" / "CONTRIBUTING.md").resolve(): ( REPO_ROOT / "CONTRIBUTING.md" - ).resolve() + ).resolve(), + (REPO_ROOT / "docs" / "community" / "code-of-conduct.md").resolve(): ( + REPO_ROOT / "CODE_OF_CONDUCT.md" + ).resolve(), } diff --git a/tests/test_docs_nav.py b/tests/test_docs_nav.py index 62b93885..0675a947 100644 --- a/tests/test_docs_nav.py +++ b/tests/test_docs_nav.py @@ -26,11 +26,12 @@ MKDOCS_FILE = REPO_ROOT / "mkdocs.yml" DOCS_DIR = REPO_ROOT / "docs" -# hooks.py copies the repository-root guide into docs/ before the build starts, -# so the nav entry for CONTRIBUTING.md is valid even though docs/CONTRIBUTING.md -# is not committed. Same mapping as tests/test_docs_links.py. +# hooks.py copies repository-root community files into docs/ before the build +# starts, so their nav entries are valid even though the generated pages are not +# committed. Same mapping as tests/test_docs_links.py. GENERATED_DOC_FILES = { "CONTRIBUTING.md": REPO_ROOT / "CONTRIBUTING.md", + "community/code-of-conduct.md": REPO_ROOT / "CODE_OF_CONDUCT.md", } # Pages that are deliberately kept out of the navigation, with the reason. diff --git a/tests/test_hooks.py b/tests/test_hooks.py index cf8a785e..4ef52ef9 100644 --- a/tests/test_hooks.py +++ b/tests/test_hooks.py @@ -16,10 +16,12 @@ 7. 其他页面的编辑链接保持不变。 8. 递归统计指定文档目录中的 Markdown 文件,忽略其他文件和目录。 9. 空文档目录的统计结果为 0。 + 10. 根目录行为准则构建时生成社区文档页。 + 11. 行为准则生成页的编辑链接指向根目录源文件。 预期运行效果: 逐项输出测试名称,通过时每项末尾显示 ok,最后显示: - Ran 11 tests in ...s + Ran 21 tests in ...s OK 实际耗时因环境而异;若显示 FAILED 或 ERROR,应检查后面的错误信息。 @@ -95,6 +97,24 @@ def test_other_page_edit_url_is_preserved(self): self.assertIs(returned, context) self.assertEqual(page.edit_url, edit_url) + def test_code_of_conduct_edit_url_points_to_root_source(self): + context = {} + page = SimpleNamespace( + file=SimpleNamespace(src_uri="community/code-of-conduct.md"), + edit_url=( + "https://github.com/OpenHUTB/.github/edit/master/" + "docs/community/code-of-conduct.md" + ), + ) + + returned = hooks.on_page_context(context, page, {"docs_dir": "/repo/docs"}) + + self.assertIs(returned, context) + self.assertEqual( + page.edit_url, + "https://github.com/OpenHUTB/.github/edit/master/CODE_OF_CONDUCT.md", + ) + class PreBuildTests(unittest.TestCase): def setUp(self): @@ -118,6 +138,14 @@ def test_copies_content_and_metadata_relative_to_hook_file(self): self.assertEqual(destination.stat().st_mtime, source.stat().st_mtime) self.assertIn("Successfully copied CONTRIBUTING.md", output.getvalue()) + def test_copies_code_of_conduct_to_community_page(self): + source = self.root / "CODE_OF_CONDUCT.md" + source.write_text("# 行为准则\n", encoding="utf-8") + with redirect_stdout(io.StringIO()): + hooks.on_pre_build({"docs_dir": str(self.root / "docs")}) + destination = self.root / "docs" / "community" / "code-of-conduct.md" + self.assertEqual(destination.read_bytes(), source.read_bytes()) + def test_repeated_build_refreshes_existing_copy(self): source = self.root / "CONTRIBUTING.md" source.write_text("first", encoding="utf-8") @@ -148,7 +176,6 @@ def test_uses_configured_docs_directory(self): ) self.assertFalse((self.root / "docs" / "CONTRIBUTING.md").exists()) - class PostBuildTests(unittest.TestCase): def test_counts_markdown_recursively_in_configured_docs_directory(self): with TemporaryDirectory() as temporary: