I have a confession: I love good documentation. I also love Puppet’s new documentation tool Strings, which is meant to supplant the rather fussy puppet doc command. Strings is built on the popular Ruby documentation tool YARD. Strings allows you to document your code using markdown (or RDoc) and generate beautiful documentation that’s easy to consume. I recommend checking out the Strings README for more comprehensive documentation on the format and configuration options. Strings is a Puppet Face and is delivered via a Puppet module. To use Strings, all you have to do is install the yard gem, and the puppetlabs/strings Puppet module:

$ puppet module install puppetlabs/strings
Notice: Preparing to install into /Users/ddanzilio/.puppet/modules ...
Notice: Downloading from https://forgeapi.puppetlabs.com ...
Notice: Installing -- do not interrupt ...
/Users/ddanzilio/.puppet/modules
└── puppetlabs-strings (v0.1.1)

$ gem install yard
Fetching: yard-0.8.7.6.gem (100%)
Successfully installed yard-0.8.7.6
1 gem installed

$ puppet help strings

USAGE: puppet strings <action>

Generate Puppet documentation with YARD.

OPTIONS:
  --render-as FORMAT             - The rendering format to use.
  --verbose                      - Whether to log verbosely.
  --debug                        - Whether to log debug information.

ACTIONS:
  server    Serve YARD documentation for modules.
  yardoc    Generate YARD documentation from files.

See 'puppet man strings' or 'man puppet-strings' for full help.

I’ve started generating documentation with Strings for all of my Puppet modules and pushing it to the gh-pages branch so it’s available in GitHub Pages. You can see an example of the kind of output generated with Strings by looking at the docs generated by my VirtualBox module here. I threw together a couple rake tasks to help with this and thought I would share:

namespace :strings do
  doc_dir = File.dirname(__FILE__) + '/doc'
  git_uri = `git config --get remote.origin.url`.strip
  vendor_mods = File.dirname(__FILE__) + '/.modules'

  desc "Checkout the gh-pages branch for doc generation."
  task :checkout do
    unless Dir.exist?(doc_dir)
      Dir.mkdir(doc_dir)
      Dir.chdir(doc_dir) do
        system 'git init'
        system "git remote add origin #{git_uri}"
        system 'git pull'
        system 'git checkout gh-pages'
      end
    end
  end

  desc "Generate documentation with the puppet strings command."
  task :generate do
    Dir.mkdir(vendor_mods) unless Dir.exist?(vendor_mods)
    system "bundle exec puppet module install puppetlabs/strings --modulepath #{vendor_mods}"
    system "bundle exec puppet strings --modulepath #{vendor_mods}"
  end

  desc "Push new docs to GitHub."
  task :push do
    Dir.chdir(doc_dir) do
      system 'git add .'
      system "git commit -m 'Updating docs for latest build.'"
      system 'git push origin gh-pages'
    end
  end

  desc "Run checkout, generate, and push tasks."
  task :update => [
    :checkout,
    :generate,
    :push,
  ]
end

You can see a complete example of how I’ve configured this in my VirtualBox module here. I’m still working on an elegant way to generate this documentation with Travis. I know all the pieces are there, I just need to put them together in a pretty package. I’ll share that when I have time! Otherwise, let me know if you have any questions or suggestions to make this better!