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