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

[John Dewey < >]

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:

https://github.com/mapleoin/chef-attrdoc

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:

https://github.com/stackforge/cookbook-openstack-compute/blob/aa42f5c09a445cde7267e4b4d00a6ce893aa481e/attributes/default.rb

-> https://gist.github.com/mapleoin/6886586

https://github.com/stackforge/cookbook-openstack-identity/blob/2e6b8b9c6788ae28fbc362c77c53a51c040b49a6/attributes/default.rb

-> https://gist.github.com/mapleoin/6886493

This is a very early release with some known bugs. I'd really like to

know what the wider chef community thinks :)

Thanks,

Ionuț

[1] https://wiki.openstack.org/wiki/Chef/GettingStarted#Code