Capable of generating attribute documentation ?

[johntdyer]

I see mention of attribute handling in this project but I see no examples of how to use it. Can yard-chef generate documentation of attributes somehow or am I reading to much into the source ?

[nitinmohan87]

'yard-chef' is capable of documenting attributes. The generated doc displays attribute in a table format (name and description being the columns). The plugin parses the attribute name and description from metadata.rb (cookbook-level attributes) and in the resources (resource attributes) directory. We are still working on the final review of design of generated documentation. All your inputs would be very valuable.

[johntdyer]

Hey,

Thanks for the quick reply but I am not exactly sure I see what you mean by "cookbook-level attributes" in the metadata.rb file. Are you talking about this?

attribute 'pets/cat/name',
 :display_name => "Cat Name",
 :description => "The name of your cat",
 :choice => [
   'kitty kitty',
   'peanut',
   'einstein',
   'honey' ],
 :type => "string",
 :required => "recommended",
 :recipes => [ 'cats::eat' ],
 :default => "kitty kitty"

If so I did try adding that to my metadata.rb file and rerunning yard-chef but I didnt get that attribute in the result. Am I perhaps doing something wrong or misunderstanding ?

Thanks again

-John

[nitinmohan87]

You should find the attribute displayed in whatever cookbook you defined your attribute in. Can you find the documentation of your cookbook in the "Cookbook List"? If so, check in that and let me know if you can find it. Otherwise it could probably be a bug.

[johntdyer]

Nitin,

Right now I have one cookbook I am testing this with ( prism )

I run the following

jdyer@dyer:~/Dropbox/Projects/chef/site-cookbooks/prism(master⚡) » bundle exec yardoc --plugin chef */.rb Files: 12 Modules: 3 ( 3 undocumented) Classes: 6 ( 5 undocumented) Constants: 0 ( 0 undocumented) Methods: 49 ( 38 undocumented) 20.69% documented

jdyer@dyer:~/Dropbox/Projects/chef/site-cookbooks/prism(master⚡) »

In the results I see this ( http://note.io/Z0VzrF ) in the bottom of the index.html file which yard is generating but that link for metadata.rb points to a file which doesnt exist

On Mon, Apr 1, 2013 at 7:54 PM, Nitin notifications@github.com wrote:

You should find the attribute displayed in whatever cookbook you defined your attribute in. Can you find the documentation of your cookbook in the "Cookbook List"? If so, check in that and let me know if you can find it. Otherwise it could probably be a bug.

— Reply to this email directly or view it on GitHubhttps://github.com/rightscale/yard-chef/issues/4#issuecomment-15744532 .

[nitinmohan87]

I think you are using the plugin from within the 'prism' directory. Try running the same command from 'site-cookbooks' directory. The plugin will then generate documentation for all cookbooks in that directory. The plugin, as of now, works only if it is run from the directory which has all the cookbooks (in your case 'site-directory'). Try that and please let me know. This is still a work in progress.

[johntdyer]

Nitin,

Great, much further now ( http://note.io/XmXLZx ) . I do have a few remaining questions if you don't mind.

1. How do I fill out the description column of the attributes ? The canonical example from the Opscode docs ( below ) doesn't seem to suffice

attribute 'pets/cat/name',
 :display_name => "Cat Name",
 :description => "The name of your cat",
 :choice => [
   'kitty kitty',
   'peanut',
   'einstein',
   'honey' ],
 :type => "string",
 :required => "recommended",
 :recipes => [ 'cats::eat' ],
 :default => "kitty kitty"

1. How do I provide more information on the recipes, for example a description of what they are for ?

   I assume for each of these you are expecting metadata to be provided in some manor which I am not doing

Thanks again

-John

[nitinmohan87]

I am working on getting the ":description" from attribute. As of now if you put a comment on top of the attribute that gets generated in the docs. For the recipes you can have description on the metadata.rb.

recipe "cookbook::recipe_name", "Recipe description"

[nitinmohan87]

I have updated the README on how to document the cookbooks. Please let me know if you still run into any issues.