[chef] Chef cookbook documentation generator from attributes files

[Ionuț Arțăriși < >]

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