Metadata-Version: 2.4
Name: py2md-cli
Version: 0.2.0
Summary: 将源代码文件递归转换为 Markdown 文档的命令行工具，支持 Python、HTML、CSS、JS、Vue、TS、JSON、XML、YAML 等多种文件类型。
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: python,markdown,documentation,code-to-markdown,cli,converter,html,css,javascript,vue,typescript
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

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

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

## 功能特性

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

## 支持的文件类型

| 类型 | 标志 | 扩展名 | 代码块标注 |
|------|------|--------|-----------|
| Python | `--py` / `-py` | `.py` | `python` |
| HTML | `--html` / `-html` | `.html`, `.htm` | `html` |
| CSS | `--css` / `-css` | `.css` | `css` |
| JavaScript | `--js` / `-js` | `.js`, `.mjs`, `.cjs` | `javascript` |
| Vue | `--vue` / `-vue` | `.vue` | `vue` |
| TypeScript | `--ts` / `-ts` | `.ts`, `.tsx` | `typescript` |
| JSON | `--json` / `-json` | `.json` | `json` |
| XML | `--xml` / `-xml` | `.xml` | `xml` |
| YAML | `--yaml` / `-yaml` | `.yaml`, `.yml` | `yaml` |

## 安装

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

## 快速开始

```bash
# 整合 Python 文件（默认）
py2md ./src
py2md ./src -py

# 整合 HTML 文件
py2md ./html_files -html

# 整合 CSS 文件
py2md ./styles -css

# 整合 JavaScript 文件
py2md ./scripts -js

# 整合 Vue 文件
py2md ./components -vue

# 整合 TypeScript 文件
py2md ./ts_src -ts

# 整合 JSON 文件
py2md ./config -json

# 整合 XML 文件
py2md ./data -xml

# 整合 YAML 文件
py2md ./config -yaml

# 指定输出文件路径
py2md ./src -py --output docs/code.md

# 使用 GBK 编码读取，并包含隐藏文件
py2md ./src -py --encoding gbk --include-hidden

# 自定义扩展名
py2md ./src -py --ext .py --ext .pyx
```

## 命令行参数

| 参数 | 缩写 | 说明 | 默认值 |
|------|------|------|--------|
| `INPUT_DIR` | — | 待扫描的目标文件夹路径（必填） | — |
| `--py` | `-py` | 整合 Python 文件（.py） | 默认行为 |
| `--html` | `-html` | 整合 HTML 文件（.html, .htm） | — |
| `--css` | `-css` | 整合 CSS 文件（.css） | — |
| `--js` | `-js` | 整合 JavaScript 文件（.js, .mjs, .cjs） | — |
| `--vue` | `-vue` | 整合 Vue 文件（.vue） | — |
| `--ts` | `-ts` | 整合 TypeScript 文件（.ts, .tsx） | — |
| `--json` | `-json` | 整合 JSON 文件（.json） | — |
| `--xml` | `-xml` | 整合 XML 文件（.xml） | — |
| `--yaml` | `-yaml` | 整合 YAML 文件（.yaml, .yml） | — |
| `--output` | `-o` | 输出 Markdown 文件路径 | `{目录名}_{类型}.md` |
| `--encoding` | `-e` | 读取源文件时使用的字符编码 | `utf-8` |
| `--exclude-hidden` / `--include-hidden` | — | 是否排除隐藏文件和目录 | 排除 |
| `--ext` | `-x` | 自定义文件扩展名（可多次指定，覆盖默认） | 按类型决定 |

## 输出示例

生成的 Markdown 文件结构如下：

```markdown
# my_project — Python 文件汇总

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

## 路径：`main.py`

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

---

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

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

---
```

## 作为 Python 库使用

### 通用接口（推荐）

```python
from py2md import files_to_markdown

# 转换 Python 文件
result = files_to_markdown(
    input_dir="./src",
    output_path="output.md",
    file_type="py",
    encoding="utf-8",
    exclude_hidden=True,
)

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

# 转换 HTML 文件
result = files_to_markdown("./html_files", "html_output.md", "html")

# 转换 Vue 文件
result = files_to_markdown("./components", "vue_output.md", "vue")
```

### 向后兼容接口

```python
from py2md import py_to_markdown, html_to_markdown

# Python 文件转换（原有接口）
result = py_to_markdown(
    input_dir="./my_project",
    output_path="output.md",
    encoding="utf-8",
    exclude_hidden=True,
)
print(f"成功率：{result.success_rate}%")

# HTML 文件转换（原有接口）
result = html_to_markdown("./html_files", "html_output.md")
```

### 文件类型配置

```python
from py2md import FILE_TYPE_CONFIG

# 查看所有支持的文件类型
for file_type, config in FILE_TYPE_CONFIG.items():
    print(f"{file_type}: {config['extensions']} -> ```{config['code_block']}")
```

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

```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/*
```

## 版本历史

### v0.3.0

- 新增多文件类型支持：HTML、CSS、JavaScript、Vue、TypeScript、JSON、XML、YAML
- 新增通用转换函数 `files_to_markdown` 和 `FILE_TYPE_CONFIG` 配置
- 新增 `FileConversionResult` 统一转换结果对象
- CLI 新增文件类型切换选项（`--py`、`--html`、`--css` 等）
- 默认输出文件名改为 `{目录名}_{类型}.md` 格式
- 保留 `py_to_markdown` 和 `html_to_markdown` 向后兼容接口

### v0.1.x

- 初始版本，支持 Python 文件递归转换为 Markdown

## 许可证

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