Updated README.md

rightscale-cookbooks · Nov 13, 2015 · 1f7396e · 1f7396e
1 parent f5ebd33
commit 1f7396e
Show file tree

Hide file tree

Showing 3 changed files with 162 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -8,48 +8,25 @@ recipes, lightweight resources and providers, libraries and definitions.
 
 ## Requirements
 
-* Ruby 1.8.7 or higher
+* Ruby 1.9 or higher
 * [YARD](http://yardoc.org/)
-* [Ripper](https://github.com/lsegal/ripper18) if you are using Ruby 1.8.x
 
 ## Installation
 
 It is available from RubyGems:
 
     gem install yard-chef
 
-If you are using Ruby 1.8.x, you need to install Ripper as well:
-
-    gem install ripper
-
 ## Documenting Your Cookbooks
 
-### Cookbook README
-The cookbook README file included in your cookbooks will be the landing page for
-each cookbook.  Under this verbatim inclusion of your README will be a
-```Cookbook Documentation``` section that contains the auto-generated information
-
-### Cookbook Metadata
-This plugin grabs most of it's information from the cookbook metadata.rb file.
-This includes the cookbook version and description, recipe descriptions,
-attribute names, and attribute descriptions.
-
-The rest of the stuff is parsed from cookbook code itself.
-
-### YARD-Chef Tags
-We also need a way to link your providers to their resources.  To do so add a
-``` @resource <resource_name>``` tag in each of your provider code.  This tag
-should be in a comment separated from other comments, for example:
-
-    # This is my super_cool provider
-    # and it does something cool.
-
-    # @resouce super_cool
+### Cookbook README.md
 
-    # Here is the first action
-    ...
+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
 
 ### 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](http://rubydoc.info/docs/yard/file/docs/Tags.md#List_of_Available_Tags)
@@ -61,24 +38,165 @@ Here is an example of adding standard YARD comments to a definition:
     # @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
 
-Here is an example of adding YARD comments to a light-weight resource:
+### 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.
 
-    # Install packages required for application server setup
+### Providers
+
+In providers will be described only actions, there you can place more detailed description of action and example of usage.
+
+Example:
+
+    # Create filesystem on specified device
+    #
+    # Example:
+    #
+    #    sys_volume 'HOME' do
+    #      device '/dev/vdc'
+    #      device 'ext4'
+    #      action :enable
+    #    end
+    action :mkfs do
+    ...
+    end
+
+### Attributes
+
+To document your attributes exists two ways, first describe it in cookbooks `metadata.rb` as described in [OpsCode documentation](https://docs.chef.io/config_rb_metadata.html)
+
+    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
     #
-    actions :install
+    # 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.
 
-      # Set of packages to be installed in addition to the base application
-      # packages
-      #
-      attribute :packages, :kind_of => Array
+### Recipes
 
-The first comment will add a description for a resource action. The second
-comment adds a description for a resource attribute. You can also use comments
-to document your light-weight provider actions.
+Recipes can be documented also in two ways, with keyword `recipe` in `metadata.rb` file of cookbook ([OpsCode documentation](https://docs.chef.io/config_rb_metadata.html)).
+
+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.
+
+### 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](http://rubydoc.info/docs/yard/file/docs/Tags.md#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
 
 ## Generating Cookbook Docs
 
@@ -100,12 +218,14 @@ 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.
 
@@ -121,6 +241,7 @@ information about YARD server see [http://yardoc.org/](http://rubydoc.info/docs/
 ## License
 
 Copyright (c) 2012 RightScale, Inc.
+Copyright (c) 2015 Aleksey Hariton (aleksey.hariton@gmail.com)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

diff --git a/templates/default/attribute/html/table.erb b/templates/default/attribute/html/table.erb
@@ -38,7 +38,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
         <td>
           <strong><%= attribute.name %></strong>
           <% if object.type == :cookbook %>
-          <br /><span>[<a href="#" onclick="return false;" class="toggleSource">View source</a>]</span><br /><span class="source_code"><%= htmlify attribute.to_json %></span>
+          <br /><span>[<a href="#" onclick="return false;" class="toggleSource">View JSON</a>]</span><br /><span class="source_code"><%= htmlify attribute.to_json %></span>
           <% end %>
         </td>
         <td><%= htmlify attribute.docstring %></td>

diff --git a/yard-chef.gemspec b/yard-chef.gemspec
@@ -3,7 +3,7 @@ Gem::Specification.new do |gem|
   gem.name        = "yard-chef"
   gem.version     = IO.read(File.join(File.dirname(__FILE__), "VERSION")).chomp
   gem.platform    = Gem::Platform::RUBY
-  gem.authors     = ['Douglas Thrift', 'Nick Stakanov', 'Nitin Mohan']
+  gem.authors     = ['Douglas Thrift', 'Nick Stakanov', 'Nitin Mohan', 'Aleksey Hariton']
   gem.email       = ["douglas@rightscale.com", "nitin@rightscale.com"]
   gem.homepage    = "https://github.com/rightscale/yard-chef"
   gem.summary     = %q{YARD plugin for Chef}