Detailed recipe description

[kohlerm]

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]

@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]

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]

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]

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

[nitinmohan87]

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

[kohlerm]

Great!
Thanks
Markus

[JeanMertz]

@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]

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]

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]

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

[nitinmohan87]

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]

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
#8 (comment).

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