py2md-cli 0.1.0

将 Python 源代码文件递归转换为 Markdown 文档的命令行工具。

py2md

🐍 将 Python 源代码文件递归转换为结构化 Markdown 文档的命令行工具。

功能特性

• 递归扫描：自动遍历目标目录下所有 .py 文件（支持自定义扩展名）
• 保留层级：输出 Markdown 中完整保留文件的目录结构路径
• 灵活配置：支持自定义编码、排除隐藏文件、多扩展名过滤等选项
• 友好 CLI：基于 Typer 的命令行接口，支持彩色输出和详细统计
• 类型安全：全面使用 Type Hints，提供 py.typed 标记文件

安装

pip install py2md

快速开始

# 最简用法：扫描 my_project 目录，自动生成 my_project.md
py2md my_project

# 指定输出文件
py2md my_project --output docs/source.md

# 使用 GBK 编码读取
py2md my_project --encoding gbk

# 包含隐藏文件/目录
py2md my_project --include-hidden

# 同时收集 .py 和 .pyx 文件
py2md my_project --ext .py --ext .pyx

命令行参数

参数	缩写	说明	默认值
INPUT_DIR	—	待扫描的目标文件夹路径（必填）	—
--output	-o	输出 Markdown 文件路径	与输入目录同名的 .md 文件
--encoding	-e	读取源文件时使用的字符编码	utf-8
--exclude-hidden / --include-hidden	—	是否排除隐藏文件和目录	排除
--ext	-x	要收集的文件扩展名（可多次指定）	.py

输出示例

生成的 Markdown 文件结构如下：

# my_project — Python 文件汇总

> **生成时间**：2026-07-08 10:30:00 UTC
> **根目录**：`/path/to/my_project`

## 路径：`main.py`

\`\`\`python
# main.py 的源代码内容
\`\`\`

---

## 路径：`utils/helpers.py`

\`\`\`python
# helpers.py 的源代码内容
\`\`\`

---

作为 Python 库使用

from py2md import py_to_markdown

result = py_to_markdown(
    input_dir="./my_project",
    output_path="output.md",
    encoding="utf-8",
    exclude_hidden=True,
)

print(f"扫描文件数：{result.files_found}")
print(f"成功：{result.files_success}")
print(f"失败：{result.files_failed}")
print(f"成功率：{result.success_rate}%")

从源码安装（开发模式）

git clone https://github.com/py2md/py2md.git
cd py2md
pip install -e ".[dev]"

构建与发布

# 构建分发包
python -m build

# 上传到 PyPI
twine upload dist/*

# 上传到 TestPyPI（测试）
twine upload --repository testpypi dist/*

许可证

MIT License