Attributes are not parsed when written in explicit style

[WalterS]

Attributes from attributes/ are not parsed when written in explicit style as "node.level" (e.g. node.default['mycookbook']['users'])

[joerg]

Hi,

Glad to see that people are actually using chefdoc. Can you give an example on where this does not work? I actually have a test fixture for this [1] which is parsed correctly, although I just found that the precedence is incorrect which I will fix soon.

yard-chefdoc/test/fixtures/test-cookbook1/attributes/header_license.rb

Line 10 in 414b830

node.default['header']['license'] = 'The header should not be the documentation of this!'

[WalterS]

Have a look at this Gist, this is how all our attribute files look like here.
I have updated the Gist with a more challenging example. We often have dynamic attributes.

[joerg]

It added the file from the gist to the fixture in test/fixtures/test_cookbook1/attributes/hped_example.rb and everything works for me (apart from the mentioned precedence). Which version are you using and how did you deploy chefdoc?

[WalterS]

I used the CLI with yardoc --plugin chef "**/*.{rb,json}" .
This is version 2.0.0 of the gem yard-chef and 0.9.12 of yard.
With node. the attributes are not parsed. Without node. I get something like this:
screenshot
(Couldn't directly insert PNG or JPEG here)
from

# Set automount. sles 11.3 and 11.4 use ldap for automount
default['my-ldap']['automount'] = node['my-ldap']['reg'].chomp('d')
if node['platform'] == 'suse' && node['platform_version'].to_f >= 11.3 && node['platform_version'].to_f < 12.0
  default['my-ldap']['automount'] = 'ldap'
end

[joerg]

Oh, you are using yard-chef [1] which is in my eyes quite old and outdated which is why I started this new project calld yard-chefdoc. There also is a webapp similar to rubydoc.info available at https://www.chefdoc.info. You can use this gem in a similar way as yard-chef but it is cookbook centric and thus has to be used on a single cookbook and not on a chef repo.
If you are interested in running chefdoc on your own servers I can gladly help you to do so since I need feedback to make this service better.

[1] https://github.com/rightscale-cookbooks/yard-chef

[WalterS]

Oh, my bad. I'll check with yard-chefdoc

[WalterS]

Now I get

$yardoc --plugin chefdoc "**/*.{rb,json}"
/usr/local/rvm/gems/ruby-2.3.4/gems/yard-chefdoc-0.1.0/lib/yard/cli/stats.rb:6: warning: already initialized constant YARD::CLI::Stats::STATS_ORDER
/usr/local/rvm/gems/ruby-2.3.4/gems/yard-0.9.12/lib/yard/cli/stats.rb:12: warning: previous definition of STATS_ORDER was here
[warn]: In file `attributes/default.rb':2: Cannot resolve link to url_particle from text:
        ...{url_particle}...
[warn]: In file `attributes/default.rb':2: Cannot resolve link to VERSION from text:
        ...{VERSION}...
 96.77% documented

because the first two lines are just header in this file:

# Recipe: my-ldap
# Attribute file: default

[WalterS]

Hmm, seems not to be so easy to have (dynamic) attributes documented automatically.
This is the whole mess of that attribute file without any changes for accommodating yard-chefdoc :D

[joerg]

Wow, this attributes file really is quite a mess (sorry). As a rule of thumb, try to use attributes only for the stuff a user really should be able to override in nodes/environments/roles/wrapper cookbooks. But thanks for the example and I will have a look at it and check if there are at least some bits that can be parsed and documented automatically.

[WalterS]

Indeed, no offense taken :) Thank you for having a look at this.