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