[chef] Re: Re: Chef cookbook documentation generator from attributes files


Chronological Thread 
  • From: "steve ." < >
  • To: " " < >
  • Subject: [chef] Re: Re: Chef cookbook documentation generator from attributes files
  • Date: Thu, 10 Oct 2013 13:49:34 -0700

I added this kind of functionality to yard-chef.  I expect to have final legal approval to submit the pull request to Rightscale any day now.  (I can talk about this since they've approved the contribution, they're just looking over the CLA now...)

It's pretty cool - if you point it at a cookbooks directory, it will actually build up a searchable index of node attributes and add that to the yardoc site.

Actually, I've just realized ... I can't submit a pull request yet (that Rightscale can legally accept) because I can't sign the CLA until I hear back that it's OK for me to do so, but it's probably safe for me to put up on GitHub now...

So, um ... I'll see if I can post that in the next couple hours.
 


On Thu, Oct 10, 2013 at 9:23 AM, John Dewey < " target="_blank"> > wrote:
Nice work Ionuț.  I like where this is going, especially for the stack forge openstack cookbooks.

John

On Thursday, October 10, 2013 at 8:09 AM, Ionuț Arțăriși wrote:

Hello,

I started working on a project to generate README (markdown)
documentation from attributes files:

This project started while working on the openstack cookbooks[1]. The
attributes files there have a lot of comments that would be useful for
users: which attributes are available to be configured and what they do,
how etc. This documentation also has the advantage of being more valid
and up-to-date since it is in the code.

README files don't get nearly as many changes as the comments in the
attributes files. However, the README is generally the frontpage of a
cookbook which users generally go to read. So it would make sense to
have the documentation mirrored from the attributes files.

chef-attrdoc looks at the attributes/default.rb file, groups blocks of
attribute assignments with the first comment above them and then inserts
all of this into the cookbook README's Attributes section.

I am aware of other tools which generate documentation from cookbook
filse, but they either do not use the attributes file as a source or
ignore comments.

Here are some examples of generated attributes sections from openstack
cookbooks:



This is a very early release with some known bugs. I'd really like to
know what the wider chef community thinks :)

Thanks,
Ionuț







Archive powered by MHonArc 2.6.16.

§