Generating Ruby API docs for developing extensions
For documentation on Puppet’s Ruby APIs for developing low-level extensions to Puppet, you can generate your own local copy of Puppet’s YARD (Yay! A Ruby Documentation) content. Generating these docs ensures that you always have the correct, relevant Ruby API docs for your version of Puppet.
Before you begin
To generate YARD content, you need:
- Command-line access to your workstation
- Ruby (tested on Ruby 2.3 and later)
Generating YARD content
To generate YARD content, you must have a local copy of the Puppet code repository and the Ruby
bundler gem. If you’re already developing Puppet extensions in Ruby, you might have already performed some of these steps, and it’s safe to skip any that you’ve already completed.
Clone the Puppet code repository to your local workstation using git.
git clone https://github.com/puppetlabs/puppet
This creates a directory named “puppet” in your current working directory.
Enter the directory.
bundlergem if it isn’t already installed.
gem install bundler
bundlerinstall this project’s prerequisites.
If you want to only generate YARD content and aren’t interested in developing Ruby extensions using this copy of the Puppet code, you can speed up this process by adding the
--without development extraoption:
bundle install --without development extra
Run the YARD tool, which should have been installed by
The YARD tool will generate the content into a new
docfolder inside your current working directory. The
docdirectory is already in the Puppet repository’s
.gitignorefile, so they should not be exposed to git’s workspace if you generate them inside of the repository. To generate the docs to a specific directory, use the
YARD generates many warning messages. To silence these messages, run
yard docwith the
Open the generated HTML in your workstation’s web browser. The
_index.htmlfile is an alphabetical index, and
index.htmlis the YARD-rendered output of the Puppet repo’s README file. Both are good starting points for navigating the YARD content.