自动生成 HTML 文档

An expert is someone who is one page ahead of you in the manual.

— David Knight

像大多数工程师一样，我从来没有阅读过手册，除非或者直到产品实际出现了十万火急的情况。 然而，随着你的配置清单代码不断增多且越来越复杂，使用 Puppet 的自动文档工具 puppet doc 为你的节点（node）和类（class）生成 HTML 文档是非常有用的。

操作步骤

在你的配置清单目录下运行如下的 puppet doc 命令：

puppet doc --all --outputdir=/var/www/html/puppet --mode rdoc \
  --manifestdir=/etc/puppet/manifests/

工作原理

puppet doc 在 /var/www/html/puppet 目录下生成结构化的 HTML 文档树， 这与 RDoc 生成的文档很类似，RDoc 是流行的 Ruby 文档生成器。 这使理解不同配置清单代码之间的相互关系便得更容易， 因为你可以点击被包含的类名称便能看到它的定义。

更多用法

puppet doc 将根据你当前的配置清单生成基本的文档。 然而，你可以在你的配置清单文件中使用标准的 RDoc 语法包含更多的有用信息。 下面是一个在类中添加一些注释文档的例子：

class puppet {
 # This class sets up the Puppet client.
 #
 # ==Actions
 # Install a cron job to run Puppet.
 #
 # ==Requires
 # * Package["puppet"]
 #
    cron { "run-puppet":
        command => "/usr/sbin/puppet agent --test >/dev/null 2>&1",
        minute => inline_template("<%= hostname.hash.abs % 60 %>"),
    }
}

你在文档中为每个类添加的注释，会显示在生成的 HTML 文件里，如图所示：