01 Apr 2013Documenting Cookbooks
Our infrastructure has many cookbooks that aim to be reusable, primarily through encapsulating behaviour in LWRPs. This led to an explosion of LWRPs and sometimes the documentation didn't keep up or did just not exist.
Chef has been evolving rapidly and many of the pain points are being addressed by Opscode or by the community at large - which is great. However, one pain point that is not getting easier is writing cookbook documentation. Several threads came together last week to motivate me to change this.
- Incorrect documentation of LWRPs contributed to an outage.
-
Mathias Lafeldt wrote a knife
plugin that generates an initial
README.md
from themetadata.rb
file in a a cookbook. - Other languages/frameworks have tools to generate documentation from annotated source code.
So I decided to try and extend Mathias's work so that I could always regenerate
README.md
from the cookbook source code. This result in the
knife-cookbook-doc project.
knife cookbook doc DIR
As much as possible the plugin makes use of the same metadata as used by chef
when generating the documentation. The plugin will also scan the source files
for annotations present in comments. Users can also add fragments of markdown
into the doc/
directory to merge into the generated README.md
file.
The goal is to keep the code as the authoritative source of information. The hope is that keeping the documentation close to the code will help to maintain it's currency.
Getting Started
Step 1
Populate the metadata.rb
of your cookbook according to Opscode's
documentation. Particular
attention should be paid to documenting the recipes, attributes, platform
compatibility and cookbook requirements (i.e. depends, recommends, suggests etc).
Step 2
At the top of each recipe, add a detailed documentation section such as;
Step 3
In each LWRP, add detailed documentation such as;
It should be noted that the documentation of the LWRP requires that the user
document the actions, using @action <action> <description>
and the attributes
using @attribute <attribute> <description>
. This allows meaningful
descriptions for the actions and attributes to be added to the README.
The other text will be added at the start of the LWRP documentation
except if marked with @section <heading>
, in which case it will be added
to the end of the LWRP documentation.
Step 4
Finally the user should add some documentation fragments into the doc/
dir.
Most importantly you should add doc/overview.md
which will replace the first
Description
section of the readme. You should also add a doc/credit.md
which
will replace the last License and Maintainer
section in the readme. The
remaining fragments will be included at the end of the readme in lexicographic
order of the filename.
Step 5
Install the plugin and run the knife command, passing the directory of the cookbook as an argument.
Examples
For an example of a README generated by the plugin, check out the glassfish cookbook. Unfortunately the plugin highlights the fact that so much of the cookbook is poorly documented. However there are some LWRPs such as glassfish_mq that have the beginning of useful documentation.
Final Thoughts
The plugin is raw but usable now. It needs to evolve to be a more seem-less part of our workflow. It would also be nice to see it or something more complete be adopted by the rest of chef community. I wonder what needs to be done to build such a tool?
References
- knife-cookbook-doc - the new plugin.
- knife-cookbook-readme - the original plugin.
- chef-glassfish - example cookbook using the new plugin.
Updates: 3rd of April, 2013
- Added References section.
- Added inline links.
- Added notes about the credit section.
- Fixed some unclear language.