rightscale-cookbooks / yard-chef

YARD-Chef

• YARD-Chef
  • Description
  • Requirements
  • Installation
  • Documenting Your Cookbooks
    • README.md
    • Resources
    • Providers
    • Attributes
    • Recipes
    • Cookbooks (metadata.rb)
      • Cookbook Dependencies
    • Libraries
    • Standard YARD Tags and Comments
  • Generating Cookbook Docs
    • Rake Task
    • Command-line
  • Viewing Cookbook Docs
  • License

Description

yard-chef is a YARD plugin for Chef that adds support for documenting Chef recipes, lightweight resources and providers, libraries and definitions.

Requirements

• Ruby 2.2 or higher, travis tests 2.2.0 and 2.3.1
• YARD

Installation

It is available from RubyGems:

gem install yard-chef

Documenting Your Cookbooks

README.md

The cookbook README.md file included in your cookbooks will be the landing page for each cookbook. Under this verbatim inclusion of your README.md will be a Cookbook Documentation section that contains the auto-generated information

Resources

Resource example:

# Volume ID
attribute :device, :kind_of => String
# Filesystem type
attribute :fstype, :kind_of => String, :default => 'ext4'
# Volume mount point
attribute :mount, :kind_of => String
...
# Disable volume in fstab and do umount
actions :disable
# Format volume if not formatted, mount and add entry to fstab
actions :enable
# Do volume format via mkfs
# Will do nothing if any filesystem already exists on volume
actions :mkfs

Comment above the attribute will be used as description for resource attributes in resource attributes table in documentation. Keyword :kind_of will be used as for type column and :default as default value column.

To have better documentation of our resources, please describe each action separately with keyword actions and comment above it. Actions will be also described in providers, so use this description as short summary for action.

If you want to see list of providers for your resource, please use YARD tag @resource in your providers (check Providers section)

Providers

In providers will be described only actions, there you can place more detailed description of action and example of usage.

Example:

# @resource sys_volume

#
# Create filesystem on specified device
#
# @example Create EXT4 partition on `/dev/vdc`
#    sys_volume 'HOME' do
#      device '/dev/vdc'
#      device 'ext4'
#      action :enable
#    end
#
# @note *WARNING!* Please use this action carefully
action :mkfs do
...
end

If you add tag @resource in the beginning of your provider you will see this provider in providers list of resource.

Tag @example used for code examples, text after tag will be used as title for code example. Please not that code example should have two spaces indent in each line.

Tag @note used for warning or additional info highlight.

Attributes

To document your attributes exists two ways, first describe it in cookbooks metadata.rb as described in OpsCode documentation

attribute "repo/default/revision",
  :display_name => "Repository Branch/Tag/Commit",
  :description =>
    "The specific branch, tag, or commit (SHA) of the specified" +
    " Git/Subversion repository that the application code will" +
    " be retrieved from. For Git repositories, use 'master'" +
    " to retrieve the master branch from the repository." +
    " For SVN repositories, use 'HEAD' to retrieve the latest changes" +
    " from the repository. Example: mybranch",

Attribute description will be received from :description section. But this method requires too many efforts to keep it up-to-date, always actual attributes will be placed in cookbook/attributes/*.rb file, so better to comment attributes there:

#
# Default Yum repos
#
# String "http://192.168.1.100/mrepo/..." should be last element in `:baseurl` array, to be first
# RPMs mirror for `yum`
default[:sys][:yum_repos] = {
    'epel_local' => {
        :description => 'Extra Packages for Enterprise Linux [LOCAL]',
        :baseurl  => %w(
          http://mirror.euserv.net/linux/fedora-epel/$releasever/$basearch/
          http://dl.fedoraproject.org/pub/epel/$releasever/$basearch/
          http://192.168.1.100/mrepo/EPEL$releasever-$basearch/RPMS.os/
        ),
        :gpgcheck => false,
        :enabled => true
    },
    ...
}

Attribute default[:sys][:yum_repos] will be added in Cookbook attributes table, comment above as description and 'epel_local' => ... will be added as default value for this attribute.

Recipes

Recipes can be documented also in two ways, with keyword recipe in metadata.rb file of cookbook (OpsCode documentation).

Example:

recipe 'cluster::converge',
       'Create instance and run converge'

First argument will be recipe name, second recipe short description, this data will be used in Recipes summary section of cookbook documentation.

To add long description of recipe, please add in the begining of your recipe comment section with leading string *Description:*, like in example below:

#
# Cookbook Name:: cluster
# Recipe:: create
#
# Copyright 2015, YOUR_COPYRIGHT
#
# All rights reserved - Do Not Redistribute
#

# *Description*
#
# to create and provision one node set NODENAME ENV variable like: `NODENAME="..."`
#
# usage:
#
#     NODENAME="risk01" chef-client -E "env" -c ~/.chef/knife.rb --runlist "recipe[cluster::converge]"
#
# ...

# cluster name
cluster_name = ENV['OPSCODE_ORGNAME']

Comment section beggining from *Description* till ... will be used as detailed description of recipe in Recipe details section of cookbook documentation. Please note, that first line of your code in recipe should have it own comment, in example above cluster_name = ENV['OPSCODE_ORGNAME'] have its own comment.

You can also use tags @note and @example like for providers.

Cookbooks (metadata.rb)

Short cookbook description and version will be received from keyworks description and version in metadata.rb file:

description      'Installs/Configures Elastic Search cluster'
version          '3.2.0'

This fields will be used in cookbooks list on the index page of your cookbooks documentation.

Cookbook Dependencies

Please describe each dependency of your cookbook with depends keyword in metadata.rb and place proper comment, why this dependency needed.

# Subversion provider for `repo` resource
depends "svn"
# Git provider for `repo` resource
depends "git"

This information will be used in Cookbook dependencies section of documentation for your cookbook.

Libraries

Comment your libraries as regular Ruby code, for more information please read list of available tags

# Search of image by name or by id
# @param name_or_id [String] image name or ID, search by name works as regexp
#   image.name =~ /#{name_or_id}/
# @return [Fog::Image] image object
def find_image(name_or_id)
   ...
end

Standard YARD Tags and Comments

Your definitions, libraries, resources and providers can benefit from adding YARD tags and comments for each class and method. You can learn more about the tags from yardoc.org and the list of available tags

Here is an example of adding standard YARD comments to a definition:

# Does a database backup.
#
# @param [String] backup_type If 'primary' will do a primary backup using volumes. If 'secondary' will do a backup S3.
#
# @raise [RuntimeError] If database is not 'initialized'
# @return [Boolean] status if backup done or not
define :db_do_backup, :backup_type => "primary" do
  ...
end

Generating Cookbook Docs

Rake Task

For generating documentation it is recommended to create a rake task:

require "rubygems"
require "chef"
require "yard"

YARD::Config.load_plugin 'chef'
YARD::Rake::YardocTask.new do |t|
  t.files = ['<path_to_cookbooks_repo>/**/*.rb']
  #t.options = ['--debug']
end

Then just run

rake yard

Command-line

From the root of your cookbook repository, run the yardoc command to generate documentation using the following command

yardoc '**/*.rb' --plugin chef

Viewing Cookbook Docs

YARD output will be present in a folder named "doc" which will be located in the same folder from where the command was run.

It is recommended to view these pages from a running YARD server. To start a local YARD server you should be in the same directory that contains your generated ./doc directory. Once there run:

yard server --reload -B localhost -p 8000 --plugin yard-chef

Add a -d option flag to run the server in daemon mode. For more information about YARD server see http://yardoc.org/

License

Copyright (c) 2012 RightScale, Inc.

Copyright (c) 2015 Aleksey Hariton ([email protected])

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Maintained by the RightScale ServerTemplate Team

yard-chef's Issues

Detailed recipe description

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?

Capable of generating attribute documentation ?

I see mention of attribute handling in this project but I see no examples of how to use it. Can yard-chef generate documentation of attributes somehow or am I reading to much into the source ?

Mode to treat cookbook as root object

Currently the plugin treats a repository as the root level object. For those of us that publish public cookbooks or have a workflow heavily informed by Berkshelf it would be nice to be able to treat our cookbook as the root of the documentation.

We don't generate documentation for an entire Gemfile, just for the gem we are developing. I think we should at least support the option for the same behavior.

Issues while parsing attributes

I am facing an issue where attributes are not getting parsed properly. I don't see description, default values etc.
I am not too sure if the plugin is getting loaded properly.
Tried with ruby 4.6.0 and 4.3.1

Ran: yardoc './**/*.rb' --plugin chef --verbose

Following is what I see in UI: (missing description and default values)

Thanks in advance for the help.

LWRP names incorrect when using provides

LWRP names seem to be generated automatically using <coobkook_name>_<resource_name> which is correct for definitions, but not necessarily for LWRPs. According to the chef docs a "provides" can be defined, which specifies the LWRPs name (https://docs.chef.io/lwrp_custom_resource.html#provides).

Generating Yard documentation for existing LWRP's

Hi Team,
Thanks for fantastic library. My requirement is - I want to show cookbook's LWRP documentation. Is there any way to show this. Here is the code from my recipe-

#Install 'splunkforwarder' package
package 'splunkforwarder' do
  version node['sap-splunk-client']['version']
  action :install
  not_if { File.exist?("#{node['sap-splunk-client']['splunk_home']}/splunk-#{node['sap-splunk-client']['version']}-x86_64-manifest") }
end

I am expecting something to show under resource-

Can you please help me??

How to document dynamic attributes?

How would we document dynamic attributes? Previously, we had all attributes documented in metadata.rb which gave us maximum control over how the attributes are documented. But this is deprecated in Chef 13 and will be removed in Chef 14 according to the Chef documentation.
We have a lot of cookbooks where attributes are defined in run-time according to architecture, network zone an so on where it seems not to be feasible to generate a documentation from the attributes file (see an example here).
Is there another way to store the attribute definitions?

N.b. If you use the explicit attribute notation node.level yard-chef just ignores them.

Yard dependency needs to be for a later version

Hi,

Awesome project, thank for doing this.
It seems that your code uses YARD::DocstringParser which is not available in yard 0.7 (as indicated in the Gemfile) but is there in the latest release (I didn't test other 0.8.x release). I suggest that you update the dependency requirement.

Also, any change of releasing the gem on rubygems.org? That would be great!

minor documentation typo

In README.md,

YARD::Config.load_plugins 'chef'

should really say

YARD::Config.load_plugin 'chef'

Cheers
Stephan

Redcarpet 3

Any particular reason Redcarpet is locked at version 2?