Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ tests/_tmp/
# mkdocs 构建产物(本地 serve/build 生成)
site/
docs/CONTRIBUTING.md
docs/community/code-of-conduct.md

# 脚本与工作流产物
commit_stats.csv
Expand Down
55 changes: 33 additions & 22 deletions hooks.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {}

Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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,
)


# 构建完成后,输出文档构建统计信息
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ nav:

# 以下为补充收录的文档页面
- 贡献相关:
- 社区行为准则: 'community/code-of-conduct.md'
- 基于浏览器的贡献指南: 'codespace.md'
- 注册 Github 账号: 'dev/sign_up.md'
- 使用 VScode 推送代码: 'dev/vscode_push.md'
Expand Down
7 changes: 5 additions & 2 deletions tests/test_docs_links.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
}


Expand Down
7 changes: 4 additions & 3 deletions tests/test_docs_nav.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
31 changes: 29 additions & 2 deletions tests/test_hooks.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,应检查后面的错误信息。
Expand Down Expand Up @@ -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):
Expand All @@ -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")
Expand Down Expand Up @@ -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:
Expand Down
Loading