[chef] Re: Aw: Re: Documenting Cookbooks

[Peter Donald < >]

On Wed, Apr 3, 2013 at 2:02 PM, Mike < " target="_blank"> > wrote:

Have we all forgotten about yard-chef? https://github.com/rightscale/yard-chef

Interesting ... I never knew about it. It does seem a little abandoned or at least the instructions don't seem to work. It has a more interesting approach to collecting the metadata which is better in some ways. However it is still heavily focused on describing the code rather than providing user-level documentation.

On Wed, Apr 3, 2013 at 5:28 PM, Oleg Volotov < " target="_blank"> > wrote:

Now to extract the blocks, I use my program. It searches with regular expressions the blocks, deletes the additional content and paste them into a simple text file with the extension ".md".

The approach I was using is not that much more sophisticated than that :)

 

On Wed, Apr 3, 2013 at 9:57 PM, Brian Akins < " target="_blank"> > wrote:

I've always been a big fan of documenting the code "with the code."  I find it odd to document the attributes in the metadata.rb rather than the attributes file(s). Same with recipes, etc. 

I agree. An early version of the plugin actually did this by executing the attribute files. I ran into problems where some of the cookbooks actually had logic in them - particularly when interacting with ohai data and this was difficult to mock out. In theory you could go back to a regex/extract approach but that also has it's own problems.

On Thu, Apr 4, 2013 at 12:13 AM, Dimitri Aivaliotis < " target="_blank"> > wrote:

What do you think?  Would this be possible with the plugin?

My plan was to have an foodcritic plugin that verified the metadata.rb from the attributes file but it would certainly be possible to update the metadata.rb from the source. You could also add in the authoritative list of recipes based on scanning the source ...

On Fri, Apr 5, 2013 at 12:27 AM, Jeff Blaine < " target="_blank"> > wrote:

Above all, I think it's essential to the Chef community/ecosystem
that there's 1 acknowledged and recommended way to do cookbook
documentation.

+1

--
Cheers,

Peter Donald