企业官网建设流程全解析

Erlang文档生成终极指南：erlang.mk三大方案EDoc、Asciidoc与Sphinx快速上手对比

【免费下载链接】erlang.mkA build tool for Erlang that just works.项目地址: https://gitcode.com/gh_mirrors/er/erlang.mk

erlang.mk是 Erlang 生态中最省心（"just works"）的构建工具，内置了三种互补的文档生成方案：EDoc自动生成 API 参考文档、Asciidoc构建用户指南与手册页、Sphinx输出多格式专业文档。本文将带你快速理清三者的定位差异，掌握各自的配置要点，让你用最少的配置做出专业的 Erlang 项目文档。

🎯 三大文档方案速览：一张表看懂怎么选

💡 三者并非互斥——执行make docs时，erlang.mk 会自动把满足条件的方案全部构建出来（见 core/docs.mk 中的docs-deps聚合逻辑）。

📝 方案一：EDoc——从代码注释自动生成 API 文档

EDoc 是 Erlang 官方的文档工具，erlang.mk 在 plugins/edoc.mk 中为其提供了轻量封装：它扫描你的模块源码注释，直接生成 HTML 格式的函数参考文档。

三步开启 EDoc 文档生成

1. 在模块头注释中写 EDoc 注释：模块和每个导出函数上方用%注释块说明用途、参数和返回值，格式遵循 EDoc 用户指南规范；
2. 创建doc/overview.edoc文件：只要该文件存在，make docs就会自动触发 EDoc 生成（这是 erlang.mk 的默认约定）；
3. 执行构建：

make edoc # 只构建 EDoc 文档 make docs # 构建全部文档（含 EDoc，若满足条件）

常用 EDoc 配置项

• EDOC_OPTS：追加 EDoc 参数。常见用法是引入edown应用，在注释中支持Markdown 语法；
• EDOC_OUTPUT：输出目录，默认doc；
• EDOC_SRC_DIRS：多应用项目中可设为$(ALL_APPS_DIRS)，一次性为所有应用生成文档（注意须在 Makefile 末尾、include erlang.mk 之后配置）。

如果不想创建overview.edoc文件，也可以直接在 Makefile 中加一行docs:: edoc来手动挂钩。

📚 方案二：Asciidoc——生成用户指南 PDF 与 Unix 手册页

Asciidoc 方案（plugins/asciidoc.mk）适合编写面向最终用户的长篇指南：它可以自动构建用户指南 PDF、分块 HTML 文档和 Unix man 手册页。项目自身的用户指南就是用它写的，入口文件位于 doc/src/guide/book.asciidoc，可直接作为范例参考。

目录约定与构建目标

erlang.mk 对文件位置有明确约定：

• 用户指南：doc/src/guide/，入口固定为doc/src/guide/book.asciidoc
• 函数参考手册：doc/src/manual/

常用命令：

make asciidoc # 构建全部 Asciidoc 文档 make asciidoc-guide # 只构建用户指南 make asciidoc-manual # 只构建手册页 make install-docs # 安装 man 手册页到系统

⚠️前置依赖：系统需安装 Asciidoc、xsltproc 和 dblatex 三个工具，否则 PDF 无法生成。

手册页安装技巧

• MAN_INSTALL_PATH控制安装路径，默认/usr/local/share/man，可自定义为如/opt/share/man；
• MAN_SECTIONS控制安装的章节，默认3 7（模块用第 3 节、应用本身用第 7 节是良好实践）。

🔧 方案三：Sphinx——多格式输出的专业文档引擎

Sphinx 方案（plugins/sphinx.mk）基于 reST 标记语言，能输出HTML、man 页、Texinfo、LaTeX等多种格式，是三者中扩展性最强的。

最小化 Sphinx 配置：两个文件即可起步

1. doc/conf.py：项目元信息配置，最少只需四行——project（项目名）、version/release（版本号）、master_doc = 'index'、source_suffix = '.rst'；
2. doc/index.rst：入口文档，写一个标题加.. toctree::目录树即可组织整个文档结构，并可用:ref:genindex和 `:ref:`search链接自动生成术语索引与搜索页。

之后执行make sphinx即可将 HTML 文档输出到html目录。

关键配置变量清单

生成 man 页时，需在conf.py中定义man_pages列表（源文件、页名、标题、作者、章节号），例如源文件doc/mytool.rst会生成man/mytool.1。

⚖️ EDoc vs Asciidoc vs Sphinx：如何选择？

• 只想给函数和模块写参考文档→ 选EDoc，零额外写作成本，注释即文档；
• 要给用户提供完整的安装/使用/操作手册（含 PDF 和 man 页）→ 选Asciidoc，erlang.mk 官方指南本身就是它的作品；
• 需要文档站搜索、多格式输出、跨语言团队协作→ 选Sphinx，生态最丰富、格式覆盖最广；
• 大型多应用项目→ 三者组合：EDoc 管 API，Asciidoc/Sphinx 管用户指南，一个make docs全搞定。

✅ 最佳实践清单

1. 无论选哪个方案，先保证make docs能一键产出全部文档；
2. EDoc 注释建议搭配edown获得 Markdown 书写体验；
3. Asciidoc 指南入口永远放在doc/src/guide/book.asciidoc，手册模块放第 3 节；
4. Sphinx 文档默认放doc目录，用SPHINX_FORMATS增量添加输出格式；
5. 用make distclean可随时清理所有文档产物，避免陈旧文件干扰。

erlang.mk 的文档体系设计哲学是"约定优于配置"：遵守目录约定后，绝大多数项目一行额外配置都不需要。掌握本文的三种方案与配置变量，你就能为任何规模的 Erlang 项目快速搭建出专业、易读的文档体系。🚀

【免费下载链接】erlang.mkA build tool for Erlang that just works.项目地址: https://gitcode.com/gh_mirrors/er/erlang.mk