kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
31 Commits 1 Branch 14 Tags 1.1 MiB
Ruby 92.6%
HTML 7.3%
Go to file
Charlie Sharpsteen e2a9e40f01 Add a modules action to the yardoc face 
This commit adds the `puppet yardoc modules` action which is designed to
process Puppet Modules in the same way `yard gems` processes Ruby Gems. This
action walks the list of modules generated by `puppet module list` and
generates a YARD index (.yardoc directory) in each module root. This index
contains all the data required to generate documentation using other YARD
tools.
 		2014-06-01 18:03:21 -07:00
lib Add a modules action to the yardoc face 2014-06-01 18:03:21 -07:00
spec Initial commit 2014-05-16 10:57:24 -07:00
.gitignore Add Bundler artifacts to .gitignore 2014-05-25 19:11:32 -07:00
README.md Add README.md 2014-05-30 12:23:10 -07:00
Rakefile Initial commit 2014-05-16 10:57:24 -07:00
metadata.json Remove dependency on puppetlabs-stdlib 2014-06-01 11:43:59 -07:00

README.md

Puppet YARDoc

A Puppet Face and plugin built on the YARD Documentation Tool and Puppet Future Parser.

WARNING: This is very much a science experiment in progress. Things may blow up or change rapidly depending on the Temperature in Portland on a given day.

Installation

Currently, just git clone directly into the Puppet modulepath. Ensure the yard and rgen gems are installed. If running Ruby 1.8.7, ensure the backports gem is installed.

Usage

Documenting a module:

cd /path/to/module
puppet yardoc

This processes README and everything in manifests/**/*.pp.

Documenting specific manifests:

puppet yardoc some_manifest.pp [another_if_you_feel_like_it.pp]

Processing is delegated to the yardoc tool so some options listed in yard help doc are available. However, Puppet Faces do not support passing arbitrary options through a face so these options must be specified in a .yardopts file.

Caveats

  • At the moment, only top-level Classes and Defined Types are parsed and formatted.

  • Documentation blocks must immediately precede the documented code with no whitespace. This is because the comment extractor possesses the elegance and intelligance of a bag of hammers.

  • Support for Ruby 1.8.7 may disappear in the future.

  • This is a science experiment. It has a high probability of exploding catastrophically instead of doing something useful.