search

rightscale-cookbooks / yard-chef

MIT License
49 stars 16 forks source link

Detailed recipe description #8

Open kohlerm opened 11 years ago

kohlerm commented 11 years ago

I'm relatively new to yard, and yard-chef, so please forgive me if this is a stupid question.

I understand that the brief description for the recipse comes from the metadata.rb file. I've got this working, but I wonder whether there is a way to also get a more detailed description, which would be documented within the recipe file probably at the top of the file.

Is this somehow possible?

nitinmohan87 commented 11 years ago

@kohlerm - This is actually a very good question. The reason we did not read the description from the recipe file is because of how yard works. As far as I know, yard reads the comments that are attached to a specific keyword (like 'define', 'attribute', 'action', etc.). A recipe does not have a specific keyword (other than in metadata.rb) which we use in the recipe file. Hence any comments within the recipe file will be parsed as if they were part of its source code.

However, we can implement a custom yard tag (for example, @recipe) that can be defined at the top of the recipe file along with the description (for example, @recipe Description for the recipe). We can parse this tag and grab the description for the recipe.

Let me investigate more on the capabilities of yard for what else we can do. But your request is definitely possible.

kohlerm commented 11 years ago

Thanks for the quick reply! Yes, I think your are correct, that was also what I learned yesterday about yard. Only extra-files would be scanned in any case, but those have to be specificied explicitly. I don't think that makes sense for recipe files.

I like your proposal, I will ask on the yard mailing list for advise.

Oh and thanks for inventing yard-chef!

Regards, Markus

nitinmohan87 commented 11 years ago

I looked at the issue you posted to yard. We are pretty much doing what the yard owner suggests for recipes even now. We read all files inside the recipe/ folder in the cookbook and put them into the source code for the recipes. I think having a custom yard tag would make it easier for us to parse the description, otherwise the description might get lost among the other comments in the recipes.

Thanks a lot for your encouragement on this project. Means a lot to us!

kohlerm commented 11 years ago

You are welcome! I would be trying to help it implemented if I would know a little bit more about yard ...

nitinmohan87 commented 11 years ago

I can understand. We will be implementing this fix in our next dev cycle which should be beginning of next month.

kohlerm commented 11 years ago

Great! Thanks Markus

JeanMertz commented 11 years ago

@nitinmohan87 any progress on this? Would be nice to have this feature to properly document big recipes. By the way @kohlerm, as a workaround, you can always dynamically include a separate file in the metadata.rb file like so:

recipe 'base-system::default', IO.read(File.join(Dir.pwd, 'recipes', 'default.md'))
nitinmohan87 commented 11 years ago

I apologize for the delay in coming up with this feature. We were held with higher priority stories that we never had the time to get to this. Kind of a lame excuse but that's what it is. I will try to get this done during my off time. But any contributions greatly appreciated.

kohlerm commented 10 years ago

Hi, I missed that you updated this, sorry! Should this work now? I tried to use the recipe tag but it did not work for me. I installed the gem,which is maybe not updated.

tehZeno commented 10 years ago

Should this work as of today? (does not seem to work for me)

nitinmohan87 commented 10 years ago

Sorry if that commit caused confusion. This feature is not yet implemented and I don't have a specific timeline for when it would available. Any contributions are appreciated!

tehZeno commented 10 years ago

Ah yes. Thanks for the quick response. The commit was a bit confusing.

Very busy on a project currently. But If no-one else picks it up in the coming 3 months I'll have a look to see what I can contribute!

On Thu, Aug 21, 2014 at 8:52 PM, Nitin notifications@github.com wrote:

Sorry if that commit caused confusion. This feature is not yet implemented and I don't have a specific timeline for when it would available. Any contributions are appreciated!

— Reply to this email directly or view it on GitHub https://github.com/rightscale/yard-chef/issues/8#issuecomment-52965205.

Franz-Robert van Vugt | Email | Zeno@Zeno.Nu | | Phone | 06 109 233 90 | | Skype | Franz.Robert.Van.Vugt |

rshade commented 7 years ago

can you try this with 2.0?