From c152cfa5972e1713d01f1708fbb71e6400b53012 Mon Sep 17 00:00:00 2001
From: Paul Thornthwaite <paul@brightbox.co.uk>
Date: Tue, 6 Nov 2012 22:57:12 +0000
Subject: [PATCH] [Docs] Switches to using Yard for documentation

This replaces RDoc as a developer dependency with Yard to allow
use of it's tags to be more declaritive with documentation.

The Rake task for generating and uploading API docs to fog.io has also
been updated.

References #1249
---
 .gitignore  |  4 ++--
 Rakefile    | 37 ++++++++++++++++++-------------------
 fog.gemspec |  2 +-
 3 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/.gitignore b/.gitignore
index f6081d374..6dda75e34 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,17 +6,17 @@
 .bundle
 .DS_Store
 .idea
+.yardoc
 /tests/.fog
 bin/*
 !bin/fog
-!bin/rdoc
 .fog
 coverage
 doc/*
 docs/_site/*
 docs/about/supported_services.markdown
 Gemfile.lock
-rdoc
+yardoc
 pkg
 spec/credentials.yml
 vendor/*
diff --git a/Rakefile b/Rakefile
index 9b73bfce1..9daeb2e7e 100644
--- a/Rakefile
+++ b/Rakefile
@@ -1,8 +1,8 @@
 require 'bundler/setup'
 require 'date'
 require 'rubygems'
-require 'rdoc/task'
 require 'rubygems/package_task'
+require 'yard'
 require File.dirname(__FILE__) + '/lib/fog'
 
 #############################################################################
@@ -116,14 +116,6 @@ task :nuke do
   end
 end
 
-require 'rdoc/task'
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "#{name} #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -rubygems -r ./lib/#{name}.rb"
@@ -182,6 +174,13 @@ task :validate do
   end
 end
 
+# Include Yard tasks for rake yard
+YARDOC_LOCATION = "doc"
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', "README"]
+  t.options = ["--output-dir", YARDOC_LOCATION, "--title", "#{name} #{version}"]
+end
+
 task :changelog do
   timestamp = Time.now.utc.strftime('%m/%d/%Y')
   sha = `git log | head -1`.split(' ').last
@@ -271,7 +270,7 @@ end
 task :docs do
   Rake::Task[:supported_services_docs].invoke
   Rake::Task[:upload_fog_io].invoke
-  Rake::Task[:upload_rdoc].invoke
+  Rake::Task[:upload_yardoc].invoke
 
   # connect to storage provider
   Fog.credential = :geemus
@@ -397,18 +396,18 @@ task :upload_fog_io do
   Formatador.redisplay("Uploaded docs/_site\n")
 end
 
-task :upload_rdoc do
+task :upload_yardoc do
   # connect to storage provider
   Fog.credential = :geemus
   storage = Fog::Storage.new(:provider => 'AWS')
   directory = storage.directories.new(:key => 'fog.io')
 
-  # write rdoc files to versioned 'folder'
-  Rake::Task[:rdoc].invoke
-  for file_path in Dir.glob('rdoc/**/*')
+  # write doc files to versioned 'folder'
+  Rake::Task[:yard].invoke
+  for file_path in Dir.glob("#{YARDOC_LOCATION}/**/*")
     next if File.directory?(file_path)
-    file_name = file_path.gsub('rdoc/', '')
-    key = '' << version << '/rdoc/' << file_name
+    file_name = file_path.gsub("#{YARDOC_LOCATION}/", '')
+    key = '' << version << "/#{YARDOC_LOCATION}/" << file_name
     Formatador.redisplay(' ' * 128)
     Formatador.redisplay("Uploading [bold]#{key}[/]")
     directory.files.create(
@@ -419,12 +418,12 @@ task :upload_rdoc do
   end
   Formatador.redisplay(' ' * 128)
   directory.files.create(
-    :body         => redirecter("#{version}/rdoc/index.html"),
+    :body         => redirecter("#{version}/#{YARDOC_LOCATION}/index.html"),
     :content_type => 'text/html',
-    :key          => 'latest/rdoc/index.html',
+    :key          => "latest/#{YARDOC_LOCATION}/index.html",
     :public       => true
   )
-  Formatador.redisplay("Uploaded rdoc\n")
+  Formatador.redisplay("Uploaded yardoc\n")
 end
 
 def redirecter(path)
diff --git a/fog.gemspec b/fog.gemspec
index b99d4bdc7..2246212d6 100644
--- a/fog.gemspec
+++ b/fog.gemspec
@@ -56,7 +56,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency('jekyll')
   s.add_development_dependency('rake')
   s.add_development_dependency('rbvmomi')
-  s.add_development_dependency('rdoc')
+  s.add_development_dependency('yard')
   s.add_development_dependency('thor')
   s.add_development_dependency('rspec', '~>1.3.1')
   s.add_development_dependency('rbovirt', '>=0.0.11')