OpenStack + Chef

Standardize on a doc generator for attributes in README

Bug #1188777 reported by Jay Pipes
12
This bug affects 2 people
Affects Status Importance Assigned to Milestone
OpenStack + Chef
Won't Fix
Wishlist
Unassigned

Bug Description

We should use a doc generator:

https://github.com/realityforge/knife-cookbook-doc
https://github.com/rightscale/yard-chef

to generate the attribute documentation in our READMEs. This will prevent the needless duplication (and inherent desynchronization) of this documentation and the attributes/default.rb doc strings.

Revision history for this message
Alexis Munyandekwe (ndekwe) wrote :

Hi , This is going to be my very first contribution on OpenStack community. I am going to work on this bug.

Changed in openstack-chef:
assignee: nobody → Alexis Munyandekwe (ndekwe)
Alexis Munyandekwe (ndekwe)
Changed in openstack-chef:
assignee: Alexis Munyandekwe (ndekwe) → nobody
Revision history for this message
Mark Vanderwiel (vanderwl) wrote :

After the Paris summit, the current thought is to just keep all the detailed descriptions for the attributes in the attributes/defaults.rb files. And cleanup the Readme's to call out just some of the major attributes with a brief use case describing how they would be used. The idea was to not try to make the Readme a attribute ref guide, but instead make it a set of user friendly notes about how to really use this cookbook at a basic level. If we focus on making the attribute files more readable with good descriptions and logical groupings, it should speak for itself.

Based upon the above, I'm going to move this to the wishlist.

no longer affects: openstack-chef/icehouse
Changed in openstack-chef:
importance: Medium → Wishlist
Revision history for this message
JJ Asghar (d-jj) wrote :

We have decided to put the attribute documentation in the code as a comment. The README should only be an overview.

Changed in openstack-chef:
status: Triaged → Won't Fix
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.