Erlang文档生成终极指南：erlang.mk三大方案EDoc、Asciidoc与Sphinx快速上手对比
Erlang文档生成终极指南erlang.mk三大方案EDoc、Asciidoc与Sphinx快速上手对比【免费下载链接】erlang.mkA build tool for Erlang that just works.项目地址: https://gitcode.com/gh_mirrors/er/erlang.mkerlang.mk是 Erlang 生态中最省心just works的构建工具内置了三种互补的文档生成方案EDoc自动生成 API 参考文档、Asciidoc构建用户指南与手册页、Sphinx输出多格式专业文档。本文将带你快速理清三者的定位差异掌握各自的配置要点让你用最少的配置做出专业的 Erlang 项目文档。 三大文档方案速览一张表看懂怎么选方案文档类型触发目标适合场景EDoc模块/函数 API 参考make edoc代码注释即文档开发者查阅Asciidoc用户指南 PDF/HTML man 手册页make asciidoc面向最终用户的完整用户手册SphinxHTML、man 页、LaTeX 等多格式make sphinx需要多种输出格式的专业文档站 三者并非互斥——执行make docs时erlang.mk 会自动把满足条件的方案全部构建出来见 core/docs.mk 中的docs-deps聚合逻辑。 方案一EDoc——从代码注释自动生成 API 文档EDoc 是 Erlang 官方的文档工具erlang.mk 在 plugins/edoc.mk 中为其提供了轻量封装它扫描你的模块源码注释直接生成 HTML 格式的函数参考文档。三步开启 EDoc 文档生成在模块头注释中写 EDoc 注释模块和每个导出函数上方用%注释块说明用途、参数和返回值格式遵循 EDoc 用户指南规范创建doc/overview.edoc文件只要该文件存在make docs就会自动触发 EDoc 生成这是 erlang.mk 的默认约定执行构建make edoc # 只构建 EDoc 文档 make docs # 构建全部文档含 EDoc若满足条件常用 EDoc 配置项EDOC_OPTS追加 EDoc 参数。常见用法是引入edown应用在注释中支持Markdown 语法EDOC_OUTPUT输出目录默认docEDOC_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/manMAN_SECTIONS控制安装的章节默认3 7模块用第 3 节、应用本身用第 7 节是良好实践。 方案三Sphinx——多格式输出的专业文档引擎Sphinx 方案plugins/sphinx.mk基于 reST 标记语言能输出HTML、man 页、Texinfo、LaTeX等多种格式是三者中扩展性最强的。最小化 Sphinx 配置两个文件即可起步doc/conf.py项目元信息配置最少只需四行——project项目名、version/release版本号、master_doc index、source_suffix .rstdoc/index.rst入口文档写一个标题加.. toctree::目录树即可组织整个文档结构并可用:ref:genindex和 :ref:search链接自动生成术语索引与搜索页。之后执行make sphinx即可将 HTML 文档输出到html目录。关键配置变量清单变量默认值作用SPHINX_SOURCEdoc文档源文件目录conf.py需同目录SPHINX_FORMATShtml输出格式列表可加man生成手册页SPHINX_OPTS空透传给 sphinx-build支持-D namevaluesphinx_html_outputhtml单个格式的输出目录可按格式定制生成 man 页时需在conf.py中定义man_pages列表源文件、页名、标题、作者、章节号例如源文件doc/mytool.rst会生成man/mytool.1。⚖️ EDoc vs Asciidoc vs Sphinx如何选择只想给函数和模块写参考文档→ 选EDoc零额外写作成本注释即文档要给用户提供完整的安装/使用/操作手册含 PDF 和 man 页→ 选Asciidocerlang.mk 官方指南本身就是它的作品需要文档站搜索、多格式输出、跨语言团队协作→ 选Sphinx生态最丰富、格式覆盖最广大型多应用项目→ 三者组合EDoc 管 APIAsciidoc/Sphinx 管用户指南一个make docs全搞定。✅ 最佳实践清单无论选哪个方案先保证make docs能一键产出全部文档EDoc 注释建议搭配edown获得 Markdown 书写体验Asciidoc 指南入口永远放在doc/src/guide/book.asciidoc手册模块放第 3 节Sphinx 文档默认放doc目录用SPHINX_FORMATS增量添加输出格式用make distclean可随时清理所有文档产物避免陈旧文件干扰。erlang.mk 的文档体系设计哲学是约定优于配置遵守目录约定后绝大多数项目一行额外配置都不需要。掌握本文的三种方案与配置变量你就能为任何规模的 Erlang 项目快速搭建出专业、易读的文档体系。【免费下载链接】erlang.mkA build tool for Erlang that just works.项目地址: https://gitcode.com/gh_mirrors/er/erlang.mk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考