Synchronize default attribute documentation to the README

Registered by Ionuț Arțăriși

There is currently a mismatch between where developers like to write documentation and where (first-time) users get to read it.

The customizable attributes are the primary interface which allows the user to change the behavior of the cookbook. In order to keep the documentation as close to the actual code as possible and decrease the risk of them falling out of sync, we currently document the attributes in the default attributes files. On the other hand, the first place that users go to read documentation is the README file. Ideally the attributes file and the README file would always be in sync, but this information would need to be duplicated, so an automated approach is needed.

chef_attrdoc can handle synchronizing the attributes files documentation to the README files (https://github.com/mapleoin/chef_attrdoc)

Since we cannot upload custom hooks to gerrit, we have to educate all the contributors to setup a custom commit hook or run chef_attrdoc themselves before sending patches to the attributes file. We might also need to add a jenkins gate job to ensure that chef_attrdoc is indeed being run for every commit.

Blueprint information

Status:
Not started
Approver:
Mark Vanderwiel
Priority:
Low
Drafter:
Ionuț Arțăriși
Direction:
Needs approval
Assignee:
None
Definition:
Discussion
Series goal:
None
Implementation:
Not started
Milestone target:
None

Related branches

Sprints

Whiteboard

(?)

Work Items

Work items:
Write a script or git client-side hook to run chef_attrdoc on every commit and document it in each cookbook: TODO
Add a jenkins gate job which checks that chef_attrdoc has been run on every commit: TODO
Write some general documentation on using chef_attrdoc in the context of the openstack chef cookbooks that we can then point contributors to: TODO

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.