# AutoDoc

**Repository Path**: andy-w/auto-doc

## Basic Information

- **Project Name**: AutoDoc
- **Description**: 自动生成全套项目文档
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AutoDoc — 文档组装导出系统（章节复用 + Pandoc 导出 Word）

一套开源、可私有化部署的系统：**在网页上维护「章节」内容，系统自动拼装成多份 Word 文档，
一处改动、多份文档同步更新；章节/图/表自动连续编号；格式（页边距/行距/字体/行距模式）统一可控；
自动生成签署页与改动记录。**

- **内置 Web 管理台**：多用户登录、项目制隔离、章节在线编辑（实时预览含 Mermaid 真渲染）、
  文档组合、格式模板、模板库、Git 版本历史与差异对比、一键导出/打包下载
- **Pandoc** 当渲染内核（docx 生成 + 格式母版）
- **FastAPI** 后端（app/ 多模块 + SQLite 元数据 + 异步导出）

> 全链路开源免费（Pandoc GPL / python-docx MIT / FastAPI MIT），无任何付费墙、无弹窗。
> 当前版本：**V0.0.1**

---

## 目录结构（本仓库 = 部署包）

```
autodoc/                        # 部署包根目录
├── app/                          # FastAPI 后端（main/db/auth/logic/routers×9）
├── web/                          # 前端（index.html / app.js / mermaid.min.js），容器内静态托管
├── build.py                      # 组装编排层（核心）：读配置→拉章节→编号→调 Pandoc 导出
├── server.py                     # 启动器：uvicorn 拉起 app.main:app（监听 8848）
├── skel/projects/default/        # 首次启动初始化「示例项目」的内容
│
├── requirements.txt              # Python 依赖
├── Dockerfile.exporter           # 完整版镜像（pandoc + mermaid-cli + git + 中文字体）★默认
├── Dockerfile.exporter.lite      # 精简版镜像（受限网络兜底，导出 Mermaid 用占位图）
├── docker-compose.wikiless.yml   # 一键编排：导出服务 + Nginx
├── nginx.wikiless.conf           # 反向代理：80 → 导出服务 8848
├── entrypoint.sh                 # 容器入口
├── .env.example                  # 环境变量样例（管理员口令、注册开关）
│
├── DEPLOY.md                     # ★ Linux 完整部署/升级指南
└── DOCKER_CN_MIRROR.md           # 国内服务器 Docker 镜像加速配置
```

---

## 一、一键部署（推荐，Linux 服务器）

```bash
cd autodoc
docker compose -f docker-compose.wikiless.yml up -d --build
```

- 访问：`http://<服务器IP>/`
- 首次启动自动创建管理员 **admin / Admin@123**（请尽快修改口令）

详细步骤、镜像选择（完整版/lite）、升级、排错见 **`DEPLOY.md`**。

---

## 二、本地运行（不装 Docker，开发/试用）

```bash
python -m venv venv && venv/Scripts/activate        # Windows
pip install -r requirements.txt
python server.py         # 打开 http://127.0.0.1:8848/
```

---

## 章节库写法约定（导出后生效）

- **图片**：`![题注](assets/xxx.png){#fig:label}` → 自动编号「图 N：题注」
- **表格**：表格前加 `<!--tbl:label|表题-->` → 自动编号「表 N：表题」
- **Mermaid 图**：直接写 ```` ```mermaid ```` 代码块（预览实时渲染，导出预渲染为图片并编号）；
  也可用 `<!--fig:label|图题-->` 包裹写法自定义图题
- **交叉引用**：正文写 `@fig:label` / `@tbl:label` → 自动替换为「图 N / 表 N」

---

## 章节 / 小节自动编号（单源复用关键）

- 章节库里的 `.md` **不写死序号**（如「技术方案」不带「二、」）。
- 组装层按「该章节在【当前文档】中的位置」自动编号：
  - `# 标题` → **第N章 标题**（中文数字）
  - `## 标题` → **N.M 标题**
  - `### 标题` → **N.M.K 标题**
- 同一份章节在 A 里是第 **二** 章、在 B 里可以是第 **一** 章——**拖到不同文档，序号全自动重排**。

---

## 复用如何体现

- 同一章节可**同时被多份文档引用**，磁盘上只存一份。
- 在管理台修改章节 → 重新导出 → 所有引用它的文档同步更新。
- 图/表编号在每份文档内**连续且不重复**（各文档从 1 开始计数）。

---

## 格式能力

- 纸张/页边距/页眉页脚/目录深度
- 正文/各级标题/表格/题注/图片：字体、字号、颜色、对齐
- **行距六种模式**（与 Word 一致）：单倍 / 1.5 倍 / 2 倍 / 最小值 / 固定值 / 多倍行距
- 格式模板库：保存/应用/分享格式方案

---

## 生产化说明

- 更精细格式（多栏、复杂合并单元格等）：导出后用 python-docx 后处理（已内置图片居中、表格样式等）。
- Mermaid 真渲染：完整版镜像构建时安装 `@mermaid-js/mermaid-cli`（用系统 Chromium，跳过 170MB 下载）；
  受限网络装不上时自动降级占位图，Web 预览始终是浏览器侧真实渲染。
- 编号逻辑在组装层，不依赖 pandoc-crossref 版本耦合。