[chef] Re: Re: Chef cookbook documentation generator from attributes files

[Ionuț Arțăriși < >]

On 10/13/2013 05:49 AM, Peter Donald wrote:
> Hi,
>
> On Fri, Oct 11, 2013 at 2:09 AM, Ionuț Arțăriși 
> <
>  >
>  wrote:
> > I am aware of other tools which generate documentation from cookbook
> > filse, but they either do not use the attributes file as a source or
> > ignore comments.
> The "knife cookbook doc" plugin [1] will scan the attributes directory
> to generate the README in much the same way. It also scans the recipes
> directory to build documentation for recipes from the code, LWRPs as
> well. It also allows you to mix in markdown from another location (ie.
> doc/overview.md).
>
> You can see an example of the generated readme at [2] from annotated
> source files.
>
> [1] https://github.com/realityforge/knife-cookbook-doc
> [2] https://github.com/realityforge/chef-glassfish
That's cool and I've looked at this before, though I was confused by the 
additional syntax before seeing the example.

Compared to chef-attrdoc, knife-cookbook-doc:
 - rewrites the whole README file and requires additional template 
files, whereas chef-attrdoc just looks for the Attributes section and 
rewrites that, leaving everything else intact
 - does not support groups of attribute declarations documented at the 
same time; only one-to-one comment to attribute
 - doesn't handle hashes, the generated output is: Defaults to `{ ... }`
 - requires additional markdown, comment lines have to start with #<>
 - requires knife and all its dependencies which also adds to the 
startup time (the entire doc run is 4 seconds here, vs 0.1 for chef-attrdoc)

It's not clear which are advantages and which are disadvantages (and I'm 
biased) so I'll just leave this list as is. It would be cool to get some 
opinions on these differences :)

-Ionuț