自动生成 HTML 文档

优质

小牛编辑

144浏览

2023-12-01

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 文件里，如图所示：