# ohos-doc-scraper

**Repository Path**: zeroicey/ohos-doc-scraper

## Basic Information

- **Project Name**: ohos-doc-scraper
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenHarmony 文档爬虫

一个用于爬取华为 HarmonyOS 官方文档并转换为 Markdown 格式的工具。支持按树形结构保存、断点续传、实时保存等功能。

## ✨ 特性

- 🚀 **自动爬取** - 从华为开发者社区 API 自动爬取所有文档
- 📝 **Markdown 转换** - 使用 `html2text` 将 HTML 专业转换为 Markdown 格式
- 🌲 **树形结构** - 按照原文档的层级结构保存到本地目录
- ⚡ **断点续传** - 自动跳过已下载的文档，支持中断后继续
- 💾 **实时保存** - 边爬取边保存，无需等待全部完成
- 📊 **进度显示** - 实时显示爬取进度和统计信息

## 📦 安装

### 使用 UV（推荐）

```bash
# 克隆项目
git clone <repository-url>
cd openharmony_docs

# UV 会自动安装依赖
uv sync
```

### 使用 pip

```bash
pip install -r requirements.txt
# 或手动安装
pip install requests html2text
```

## 🚀 使用

### 基本用法

```bash
# 使用 UV 运行
uv run main.py

# 或直接运行
python3 main.py
```

### 测试爬取（只爬取前 3 个文档）

```bash
uv run test_fetch.py
```

### 查看文档树形结构

```bash
uv run extract_tree.py
```

## 📁 项目结构

```
openharmony_docs/
├── main.py                  # 主程序 - 爬取文档并保存
├── fetch_documents.py       # 文档爬取模块
├── html_to_markdown.py      # HTML 转 Markdown 模块
├── extract_tree.py          # 提取树形结构工具
├── test_fetch.py           # 测试脚本
├── category.json           # 文档分类目录（需手动获取）
├── pyproject.toml          # 项目配置
├── docs/                   # 输出目录 - 保存所有 Markdown 文件
│   ├── 基础入门/
│   ├── 应用开发准备/
│   └── 应用框架/
├── documents.json          # 完整文档数据（JSON）
└── documents_summary.json  # 文档摘要
```

## 📖 输出文件说明

### docs/ 目录

按树形结构保存的 Markdown 文档，例如：

```
docs/
└── 基础入门/
    ├── 应用开发导读.md
    ├── 快速入门/
    │   ├── 开发准备.md
    │   └── 构建第一个HarmonyOS应用（ArkTS）.md
    └── ...
```

每个 Markdown 文件包含：
- 文档标题
- 来源信息
- 目录（锚点列表）
- 完整内容（HTML 转换为 Markdown）

### documents.json

包含所有文档的完整数据，包括：
- `title` - 标题
- `fileName` - 文件名
- `anchorList` - 锚点列表
- `content` - HTML 内容
- `path` - 文件路径

### documents_summary.json

简化的摘要信息，便于快速查看文档结构。

## ⚙️ 配置选项

在 `main.py` 中可以修改以下参数：

```python
result = fetch_and_save_documents(
    category_file="category.json",        # 分类文件
    catalog_name="harmonyos-guides",      # 目录名称
    output_file="documents.json",         # 输出文件
    summary_file="documents_summary.json", # 摘要文件
    save_markdown=True,                   # 是否保存 Markdown
    skip_existing=True                    # 是否跳过已下载
)
```

### 其他配置

- `REQUEST_DELAY` - 请求间隔（秒），默认 0.5
- `DOCS_DIR` - 输出目录，默认 "docs"
- `API_URL` - 华为文档 API 地址

## 🔧 工具脚本

### extract_tree.py

从 `category.json` 提取并显示文档树形结构：

```bash
uv run extract_tree.py
```

输出示例：
```
OpenHarmony 文档结构树
================================================================================

基础入门
  ├─ 应用开发导读 (application-dev-guide)
  ├─ 快速入门 (quick-start)
    ├─ 开发准备 (start-overview)
    └─ 构建第一个HarmonyOS应用（ArkTS） (start-with-ets-stage)
```

### test_fetch.py

测试爬虫功能，只爬取前 3 个文档：

```bash
uv run test_fetch.py
```

## 📝 注意事项

1. **category.json** 文件需要手动从华为开发者社区获取
2. 爬取全部文档（约 5000+ 个）需要较长时间（约 40+ 分钟）
3. `docs/` 目录可能较大，已在 `.gitignore` 中排除
4. 支持中断后继续，已下载的文档会被自动跳过

## 📊 爬取统计

运行完成后会显示统计信息：

```
================================================================================
全部完成！
================================================================================
✓ 爬取文档: 5000/5060
✓ 保存文件: 5000 个 Markdown 文件
⊘ 跳过: 60 个文档（已存在）
⚠ 失败: 0 个文档
✓ 输出目录: /path/to/openharmony_docs/docs
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接

- [HarmonyOS 开发者官网](https://developer.huawei.com/consumer/cn/harmonyos/)
- [HarmonyOS 文档中心](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/)