[chef] Re: Documenting Cookbooks

[Nathen Harvey < >]

Peter,

This may be of interest, too:

http://rubygems.org/gems/knife-cookbook-readme

It was recently mentioned in the Food Fight Show newsletter.

-Nathen

From: Peter Donald < "> >
Reply-To: " "> " < "> >
Date: Tuesday, April 2, 2013 7:14 PM
To: Chef Mailing List < "> >
Subject: [chef] Documenting Cookbooks

Hi,

One of the things I have struggled with is documenting our chef cookbooks. Last week I had a few hours to spare so I put together a way of knife plugin that helps generate the README for a cookbook. The basic concept is to markup metadata.rb and the source files and generate documentation based on the annotations, similar to javadoc.

I have written up the first step at [1] but am looking for feedback on the general approach. Step 1 was to generate the README. For step 2 I am thinking of allowing you to point the tool at a chef server (or a local repository) and generate documentation for the whole set of cookbooks and thus generate the documentation for the suite (either as PDF or html).

So is this of interest to anyone else? Anyone have opinions on the best way to do this?

[1] http://realityforge.org/code/2013/04/01/documenting-cookbooks.html

--
Cheers,

Peter Donald