[chef] Aw: Re: Documenting Cookbooks

["Oleg Volotov" < >]

Hi

I do not have a lot of cookbooks, but a few big ones. Therefore I use a self written small ruby programm. My opinion was to generate a single markdown file for every text file in a cookbook within the markdown blocks like:

#begin md
# #First heading
# Some text.
# * list1
# ...
#end md

because I think in a realy huge cookbook it is not a good idea to write all explanations to one big readme file. Another reason for this is that sometimes e.g. several equivalent resources, are stacked and you do not have to describe each individually. By that it is possible to describe the behavior, less than the sysntax of a recipe, lwrp etc.
Moreover, it is also possible with this method to add normal comments for other developers.

Now to extract the blocks, I use my program. It searches with regular expressions the blocks, deletes the additional content and paste them into a simple text file with the extension ".md".

#First heading
Some text.
* list1
...

At this point I can convert them with pandoc to html or somthing else.

I know that this brings many problems with it, but my program does the job and I hope that someone else finds a better solution.
So I would be glad to get a good documentation program which will meet the requirements.

 

 

> So is this of interest to anyone else?

Yes!

A thousand times yes.

I like that it doesn't omit the undocumented stuff in
the resulting README.md.