Synchronize default attribute documentation to the README
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:/
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
- Started by
- Completed by
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