Add GitHub Pages deployment for VitePress

Author: tinyzqh

docs/.vitepress/config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Code Notes',
+  description: 'Python 代码笔记与示例',
+  lang: 'zh-CN',
+  themeConfig: {
+    nav: [
+      { text: '首页', link: '/' },
+      { text: 'Python 基础', link: '/python-basics/default_args' }
+    ],
+    sidebar: {
+      '/python-basics/': [
+        {
+          text: 'Python 基础',
+          items: [
+            { text: '默认参数示例', link: '/python-basics/default_args' }
+          ]
+        }
+      ],
+      '/': [
+        {
+          text: '指南',
+          items: [{ text: '简介', link: '/' }]
+        }
+      ]
+    }
+  }
+})
+

docs/index.md

@@ -0,0 +1,6 @@
+# 我的代码笔记
+
+欢迎来到我的代码笔记站点。这是一个用 Markdown 写笔记、从 Python 源码自动插入示例代码的仓库。
+
+可以从左侧导航进入具体的 Python 笔记页面。
+

docs/python-basics/default_args.md

@@ -0,0 +1,12 @@
+# Python 函数默认参数示例
+
+下面展示 `default_args.py` 中的 `append_item` 函数，代码来自真实的 `.py` 文件，而不是写在 Markdown 里。
+
+::: py-symbol
+path: python-demos/basics/default_args.py
+symbol: append_item
+type: function
+:::
+
+你只需要维护 `python-demos/basics/default_args.py` 中的代码，这里的函数会在构建时自动同步。
+

package.json

@@ -0,0 +1,14 @@
+{
+  "name": "code-notes-templete",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "docs:prebuild": "python scripts/expand_py_symbols.py",
+    "docs:dev": "vitepress dev docs_generated",
+    "docs:build": "npm run docs:prebuild && vitepress build docs_generated",
+    "docs:preview": "vitepress preview docs_generated"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  }
+}

python-demos/basics/default_args.py

@@ -0,0 +1,15 @@
+def append_item(item, lst=None):
+    """Append an item to a list, creating a new list by default.
+
+    This示例用于说明为什么不推荐在函数定义里使用可变对象作为默认参数。
+    """
+    if lst is None:
+        lst = []
+    lst.append(item)
+    return lst
+
+
+if __name__ == "__main__":
+    print(append_item(1))       # [1]
+    print(append_item(2))       # [2] - 不会和上一次共用列表
+

scripts/expand_py_symbols.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from extract_snippet import extract_symbol_source, SymbolType
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DOCS_DIR = ROOT / "docs"
+OUTPUT_DIR = ROOT / "docs_generated"
+
+
+BLOCK_RE = re.compile(
+    r"::: py-symbol\s+"
+    r"path:\s*(?P<path>.+?)\s+"
+    r"symbol:\s*(?P<symbol>.+?)\s+"
+    r"type:\s*(?P<type>function|class)\s*"
+    r":::",
+    re.DOTALL,
+)
+
+
+def replace_block(md_text: str) -> str:
+    def _repl(match: re.Match) -> str:
+        path_str = match.group("path").strip()
+        symbol = match.group("symbol").strip()
+        symbol_type_str = match.group("type").strip()
+        symbol_type: SymbolType = symbol_type_str  # type: ignore[assignment]
+
+        py_path = ROOT / path_str
+        code = extract_symbol_source(py_path, symbol, symbol_type)
+
+        return f"```python\n{code}\n```"
+
+    return BLOCK_RE.sub(_repl, md_text)
+
+
+def clean_output_dir() -> None:
+    if not OUTPUT_DIR.exists():
+        return
+    for p in sorted(OUTPUT_DIR.rglob("*"), reverse=True):
+        if p.is_file():
+            p.unlink()
+        elif p.is_dir():
+            p.rmdir()
+
+
+def main() -> None:
+    clean_output_dir()
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    for md_path in DOCS_DIR.rglob("*.md"):
+        rel = md_path.relative_to(DOCS_DIR)
+        out_path = OUTPUT_DIR / rel
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        text = md_path.read_text(encoding="utf-8")
+        new_text = replace_block(text)
+        out_path.write_text(new_text, encoding="utf-8")
+        print(f"processed {rel}")
+
+    print(f"All markdown files expanded into {OUTPUT_DIR}")
+
+
+if __name__ == "__main__":
+    main()
+

scripts/extract_snippet.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Literal
+
+
+SymbolType = Literal["function", "class"]
+
+
+def extract_symbol_source(py_path: Path, symbol: str, symbol_type: SymbolType) -> str:
+    """Extract the source code of a top-level function or class by name."""
+    source = py_path.read_text(encoding="utf-8")
+    tree = ast.parse(source)
+
+    lines = source.splitlines()
+
+    target_node: ast.AST | None = None
+    for node in tree.body:
+        if symbol_type == "function" and isinstance(node, ast.FunctionDef) and node.name == symbol:
+            target_node = node
+            break
+        if symbol_type == "class" and isinstance(node, ast.ClassDef) and node.name == symbol:
+            target_node = node
+            break
+
+    if target_node is None:
+        raise ValueError(f"Symbol {symbol!r} ({symbol_type}) not found in {py_path}")
+
+    # Python 3.8+ provides end_lineno on AST nodes
+    if not hasattr(target_node, "end_lineno"):
+        raise RuntimeError("Python version is too old: AST nodes lack end_lineno")
+
+    start = target_node.lineno - 1  # convert to 0-based index
+    end = target_node.end_lineno  # inclusive in terms of 1-based line numbers
+
+    snippet_lines = lines[start:end]
+    return "\n".join(snippet_lines)
+
+
+__all__ = ["extract_symbol_source", "SymbolType"]
+