risshe92/docprobe

# Docprobe Docprobe 是一个通用的文档提取工具，旨在归档那些不提供可下载版本的现代文档网站。 它会自动检测常见的文档框架，如 Docusaurus、MkDocs、GitBook 和 ReadTheDocs，然后使用智能回退策略提取内容。 ## 功能特性 - 自动检测文档平台 - 提取动态 SPA 文档站点 - 工具栏爬取和侧边栏导航发现 - 智能提取回退：Markdown → 文本 → OCR - 并发爬取 - 恢复中断的爬取任务 - 后处理：按章节标题重命名文件，去除导航样板内容 - PDF 导出支持（分页或单个合并手册） - 支持针对难处理或图片密集页面的 OCR - 专为现代 JavaScript 渲染的文档门户设计 ## 支持的文档平台 - Docusaurus - MkDocs - GitBook - ReadTheDocs - 自定义 SPA 文档站点 - PDF 查看器风格的文档页面 - 通过 OCR 回退处理图片密集的文档页面 ## 安装说明 **1. 克隆代码仓库** ``` git clone https://github.com/risshe92/docprobe.git cd docprobe ``` **2. 创建并激活虚拟环境** ``` python3 -m venv venv source venv/bin/activate ``` **3. 安装 Python 依赖** ``` pip install -r requirements.txt ``` **4. 安装 Playwright 浏览器依赖** ``` playwright install chromium ``` **5. 安装系统依赖** Debian/Ubuntu: ``` sudo apt install tesseract-ocr pandoc texlive-xetex ``` Arch: ``` sudo pacman -S tesseract pandoc texlive-core ``` ## 快速开始 提取单个文档页面： ``` python3 docprobe.py --url https://docs.example.com/docs ``` 自动爬取文档侧边栏： ``` python3 docprobe.py --url https://docs.example.com/docs --crawl-toolbar ``` 恢复中断的爬取： ``` python3 docprobe.py --url https://docs.example.com/docs --crawl-toolbar --resume ``` 将提取的 markdown 页面导出为单独的 PDF： ``` python3 docprobe.py --url https://docs.example.com/docs --crawl-toolbar --export-pdf pdf ``` 生成单个合并的 PDF 手册： ``` python3 docprobe.py --url https://docs.example.com/docs --crawl-toolbar --export-pdf pdf-single ``` ## 命令行选项 ### 爬取选项 | 参数 | 默认值 | 描述 | |---|---|---| | `--url` | 必需 | 目标文档 URL | | `--export-as` | `md` | 输出格式：`md`、`txt`、`html`、`ocr` | | `-o`, `--output-dir` | `./output//` | 输出目录 | | `--crawl-toolbar` | 关闭 | 爬取侧边栏/工具栏中的所有链接 | | `--max-pages` | `0` (无限制) | 限制爬取的页面数量 | | `--resume` | 关闭 | 跳过已处理的 URL | | `--concurrency` | `4` | 并发爬取工作线程数 | | `--export-pdf` | `none` | 爬取后导出为 PDF：`none`、`pdf`、`pdf-single` | | `--debug` | `off` | 日志级别：`off`、`error`、`info`、`debug` | ### 后处理选项 | 参数 | 描述 | |---|---| | `--post-process` | 在现有目录上运行后处理（不进行爬取） | | `--input-dir` | 要处理的输入目录（与 `--post-process` 配合使用时必需） | | `--rename` | 使用其第一个标题或页面标题重命名文件 | | `--clean` | 去除导航样板内容和 frontmatter（仅限 markdown） | | `--export-pdf` | 处理后导出为 PDF：`pdf`、`pdf-single` | ## 导出格式 `--export-as` 控制爬取期间的输出格式： | 值 | 输出 | |---|---| | `md` | Markdown（默认） | | `txt` | 纯文本 | | `html` | 渲染后的 HTML | | `ocr` | 来自页面截图的 OCR 文本 | 默认情况下，输出会写入 `./output//`，或者如果指定了 `-o` 则写入指定目录。 ## 提取策略 使用默认的 `md` 模式时，Docprobe 会分析页面并自动应用回退链： ``` markdown → text → ocr ``` 这使得 Docprobe 能够从糟糕的 Markdown 提取中恢复，并仍然捕获难以提取的内容。 ## 后处理 后处理在已提取文件的现有目录上运行，无需重新爬取。 按章节标题重命名文件： ``` python3 docprobe.py --post-process --input-dir ./output/md --rename ``` 清理 markdown 文件中的导航样板内容： ``` python3 docprobe.py --post-process --input-dir ./output/md --clean ``` 重命名、清理，然后导出单个合并的 PDF： ``` python3 docprobe.py --post-process --input-dir ./output/md --rename --clean --export-pdf pdf-single ``` ## 输出结构 ``` output/ └── md/ # or txt/, html/, ocr/ depending on --export-as ├── 0001_overview.md ├── 0002_getting_started.md └── ... meta/ ├── run.json ├── crawl_results.json ├── toolbar.json ├── content.json └── extraction.json documentation_manual.pdf # if --export-pdf pdf-single was used ``` ## 示例命令 单页面，默认 markdown 模式： ``` python3 docprobe.py --url https://docs.example.com/docs ``` 并发爬取工具栏： ``` python3 docprobe.py \ --url https://docs.example.com/docs \ --crawl-toolbar \ --concurrency 8 \ --debug info ``` 仅爬取前 20 页： ``` python3 docprobe.py \ --url https://docs.example.com/docs \ --crawl-toolbar \ --max-pages 20 ``` 将输出保存到自定义目录： ``` python3 docprobe.py \ --url https://docs.example.com/docs \ --crawl-toolbar \ -o /home/user/docs_archive ``` 恢复之前的爬取： ``` python3 docprobe.py \ --url https://docs.example.com/docs \ --crawl-toolbar \ --resume ``` 导出为纯文本： ``` python3 docprobe.py \ --url https://docs.example.com/docs \ --crawl-toolbar \ --export-as txt ``` 强制 OCR 模式： ``` python3 docprobe.py \ --url https://docs.example.com/docs \ --crawl-toolbar \ --export-as ocr ``` ## 注意事项 - OCR 需要在系统上安装 `tesseract`。 - PDF 导出需要 `pandoc` 和 LaTeX 引擎（`xelatex`）。 - 根据前端复杂程度，某些站点可能需要针对特定站点的调整。 - 对于大规模爬取，最好使用 `--resume` 来处理中断情况。

标签：DNS解析, Docusaurus, GitBook, Markdown转换, MkDocs, OCR识别, PDF导出, Playwright, ReadTheDocs, SPA爬虫, Tesseract, 侧边栏导航, 内容抓取, 动态渲染, 命令控制, 工具栏爬取, 并发爬取, 开源项目, 数据采集, 文档归档, 文档提取, 断点续传, 特征检测, 网络调试, 自动化, 自动检测, 逆向工具, 通用工具