### 自动生成 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 文件里，如图所示：