文档 4.0：从源代码自动生成文件

软件开发中的更新周期变得越来越短，这让文件创建面临新的挑战。程序编程接口的变化，必须及时并且正确地传送进客户文件。在参考信息（例如接口描述）比例较高时，会产生巨大的维护费用。

DITA 划分了三种主题类型 – 任务、参考和设计方案。对于我的公司(Advantest 公司)，最常见的是 DITA 参考类型。参考文件占整个文件的 80 %。但可惜的是，参考文件的维护费用也是最大。迄今为止 Advantest 使用手动创建参考文件方式，也就是在 CMS 中主题中创建参考文件。随着时间的发展，源代码和文件差异越来越大，文件的可接受性也随之降低。新的软件架构为文件创建问题的带来了新的契机。现在，通过直接在源代码中记录，然后由源代码自动生成参考文件，文件和最新软件版本之间不一致的问题已经得到了解决。

从源代码生成文件的优点

从一开始在系统上就避免了源代码和相应文件之间内容不一致的情况。参考文件的结构无需重新编写，而是由软件结构确定。由源代码生成的文件还有一个突出优点是高度的交叉链接，这也提高了文件的使用价值。因为交叉引用是根据结构而生成，所以它们会自动随着结构的变化而变化。

通过自动生成，随时都具备完整且最新的参考文件。在开发过程中，公司的员工就可以对其进行使用。文件创建紧随开发周期，因此也能很好地适用于敏捷开发方法，例如 Scrum。这必然会导致与开发部门之间的紧密合作。公司也从开发部门和文件部门的有效资源投入中受益。开发者也开始在其集成的开发环境 (IDE)，如 javadoc 注释中，使用源文本文件，只要他将程序库绑定到他的项目中。能最好地理解源代码的开发者也会记录下源代码。然后技术编辑将从开发者角度出发编写文件，以及编辑成从用户角度出发最易使用的文件。

解决方法

对于自动生成的 API 文件，源代码（输入）可获得专门的句法，文件生成器（数据处理）可以读取和输出（输出）该句法。

自动生成文件最适合的语言是编程接口文件所需的编程语言，例如 Java 和 C + +。但其他结构化的信息如 XML 也能非常好地被使用。所有结构化的信息如 Java、C + + 或 XML 会利用程序如 Javadoc、Doxygen 或使用 XSLT 来进行转换。通过 Apache Ant 可以执行所有程序，以扩展进一步的任务，如将文件分配到网络服务器上。自动化进程通过 Jenkins/Hudson 进行。在这里可以方便地通过网络界面开始执行（也可以使用时间控制方式）并监控执行情况。在出现错误的情况下，Jenkins/Hudson 会自动发送一封电子邮件到安排任务时规定的电子邮件地址。任务通常为 HTML 格式，但也可以生成为其他格式。

问题和挑战

但该方法不仅仅只有优点，它也会产生需要解决的问题和挑战。首先必须培训技术文档工程师，以便能在源代码和开发部门工作环境中开展工作。软件的开发过程与文件的开发过程有差异。例如源代码管理和文件管理就有差别。大多数情况下存在不同的版本管理系统。为了能够生成和维护自动化文件，文档工程师或开发者必须熟悉该工作并创建相应的必要脚本。

也会产生内容问题。开发者对目标对象可能设定太多的先决条件；结果就是可能产生无价值的描述。自动参考文件根据定义不采用以任务为导向的方式。因此它也不应作为唯一的文件来供 API 使用。以任务为导向的“入门指南”或“新手教程”文件恰恰能帮助新手快速辨明情况。由于在源代码上的共同工作也可能产生责任问题。作者会感觉到可以不对文件完全负责，因为该文件在常规环境之外被开发。许多开发者都对 API 做出了贡献，但却缺少对 API 的整体校阅。

付诸实施

使用 Doxygen 将 C + + 源代码转化成输出格式

对于 C + +、C、C# 源代码来说，可使用 Doxygen[1]程序来生成文件。Doxygen 是基于 C 语言的 API 文件通用标准，但对于 Java 和其他语言也能发挥作用。Doxygen 可通过一个图形用户界面或命令行调出。输出格式可以产生 HTML、PDF、Latex 等格式以供使用。对于 HTML 可以使用层叠样式表 (CSS) 来调整显示。

命令行调用 doxygen -g <config-file> 会生成一个配置文件。在配置文件中现在会引用 API 源代码并规定要输出的目录。通过命令行调用命令 doxygen <config-file> 然后就会生成文件输出。调整在配置文件或层叠样式表中进行。

Java 源代码使用 Javadoc 转化成输出格式

对于 Java 源代码来说，可使用 Javadoc 程序来生成文件。Javadoc 是 Java API 文件的通用标准。程序仅对 Java 语言发挥功能。可以在集成开发环境 (IDE) 或通过命令行进行调用。此时会产生一个基于帧的 HTML 输出。Javadoc 可以通过参数调整或通过所谓的 “doclet” 来进行扩展。描述可使用层叠样式表 (CSS) 来进行调整。

Javadoc 程序是 Java 开发包 (JDK)[2]的一部分。安装完 JDK[3]之后，可以在命令行通过给定 javadoc -d <zielverzeichnis> <quellcode> 来执行 Javadoc。例如，命令行调用命令 javadoc -d C:/javadoc/test com.mypackage 会将 com.mypackage 的 Java 源代码转化为一个 HTML 帧集，然后保存到 C:/javadoc/test 中。

使用 XSL 转换 (XSLT) 将 XML 转换为输出格式

不仅仅是源代码可以自动转换成文件。XML 信息也同样适合通过 XSLT[4]来进行转换。当要创建文件的软件产品使用了 XML 模型创建软件时，就会存在 XML 信息。其他参引信息也非常适合，例如从数据库中提取的表格或者在其他部门维护的 Microsoft Excel 列表。它们无需再使用手动方式与文件同步，而是可以通过自动 XSLT 转换[5] 转换成所需的输出格式。转换需要一个程序，即所谓的 XML-Parser。该程序能将 XML 通过 XSLT 转换到其他格式（例如 Saxon-HE[6]）。

使用 Apache Ant 和 Jenkins/Hudson 自动发布

源代码到文件的转换可以利用 Apache Ant[7]和 Jenkins/ Hudson[8]自动化进行。Apache-Ant 脚本[9]中会说明，要执行的工作。使用 Jenkins/Hudson 则会通过一个网络界面[10]来控制执行情况。

结论

开发自动化系统时相对较高的初始投资在很短时间内就能回本，因为对源代码的第一次更改就能自动反映到文件中。此外，由源代码生成的文件大多数情况包含比手动方式创建文件具备更多的交叉引用，这提升了使用价值。