Metadata-Version: 2.4
Name: py2md-cli
Version: 0.1.1
Summary: 将 Python 源代码文件递归转换为 Markdown 文档的命令行工具。
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: python,markdown,documentation,code-to-markdown,cli,converter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# py2md

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

[![PyPI version](https://img.shields.io/pypi/v/py2md.svg)](https://pypi.org/project/py2md/)
[![Python Versions](https://img.shields.io/pypi/pyversions/py2md.svg)](https://pypi.org/project/py2md/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 功能特性

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

## 安装

```bash
pip install py2md-cli
```

## 快速开始

```bash
# 最简用法：扫描 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 文件结构如下：

```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 库使用

```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}%")
```

## 从源码安装（开发模式）

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

## 构建与发布

```bash
# 构建分发包
python -m build

# 上传到 PyPI
twine upload dist/*

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

## 许可证

[MIT License](https://opensource.org/licenses/MIT)
