[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
This commit is contained in:
parent
521f511dce
commit
c152cfa597
|
@ -6,17 +6,17 @@
|
||||||
.bundle
|
.bundle
|
||||||
.DS_Store
|
.DS_Store
|
||||||
.idea
|
.idea
|
||||||
|
.yardoc
|
||||||
/tests/.fog
|
/tests/.fog
|
||||||
bin/*
|
bin/*
|
||||||
!bin/fog
|
!bin/fog
|
||||||
!bin/rdoc
|
|
||||||
.fog
|
.fog
|
||||||
coverage
|
coverage
|
||||||
doc/*
|
doc/*
|
||||||
docs/_site/*
|
docs/_site/*
|
||||||
docs/about/supported_services.markdown
|
docs/about/supported_services.markdown
|
||||||
Gemfile.lock
|
Gemfile.lock
|
||||||
rdoc
|
yardoc
|
||||||
pkg
|
pkg
|
||||||
spec/credentials.yml
|
spec/credentials.yml
|
||||||
vendor/*
|
vendor/*
|
||||||
|
|
37
Rakefile
37
Rakefile
|
@ -1,8 +1,8 @@
|
||||||
require 'bundler/setup'
|
require 'bundler/setup'
|
||||||
require 'date'
|
require 'date'
|
||||||
require 'rubygems'
|
require 'rubygems'
|
||||||
require 'rdoc/task'
|
|
||||||
require 'rubygems/package_task'
|
require 'rubygems/package_task'
|
||||||
|
require 'yard'
|
||||||
require File.dirname(__FILE__) + '/lib/fog'
|
require File.dirname(__FILE__) + '/lib/fog'
|
||||||
|
|
||||||
#############################################################################
|
#############################################################################
|
||||||
|
@ -116,14 +116,6 @@ task :nuke do
|
||||||
end
|
end
|
||||||
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"
|
desc "Open an irb session preloaded with this library"
|
||||||
task :console do
|
task :console do
|
||||||
sh "irb -rubygems -r ./lib/#{name}.rb"
|
sh "irb -rubygems -r ./lib/#{name}.rb"
|
||||||
|
@ -182,6 +174,13 @@ task :validate do
|
||||||
end
|
end
|
||||||
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
|
task :changelog do
|
||||||
timestamp = Time.now.utc.strftime('%m/%d/%Y')
|
timestamp = Time.now.utc.strftime('%m/%d/%Y')
|
||||||
sha = `git log | head -1`.split(' ').last
|
sha = `git log | head -1`.split(' ').last
|
||||||
|
@ -271,7 +270,7 @@ end
|
||||||
task :docs do
|
task :docs do
|
||||||
Rake::Task[:supported_services_docs].invoke
|
Rake::Task[:supported_services_docs].invoke
|
||||||
Rake::Task[:upload_fog_io].invoke
|
Rake::Task[:upload_fog_io].invoke
|
||||||
Rake::Task[:upload_rdoc].invoke
|
Rake::Task[:upload_yardoc].invoke
|
||||||
|
|
||||||
# connect to storage provider
|
# connect to storage provider
|
||||||
Fog.credential = :geemus
|
Fog.credential = :geemus
|
||||||
|
@ -397,18 +396,18 @@ task :upload_fog_io do
|
||||||
Formatador.redisplay("Uploaded docs/_site\n")
|
Formatador.redisplay("Uploaded docs/_site\n")
|
||||||
end
|
end
|
||||||
|
|
||||||
task :upload_rdoc do
|
task :upload_yardoc do
|
||||||
# connect to storage provider
|
# connect to storage provider
|
||||||
Fog.credential = :geemus
|
Fog.credential = :geemus
|
||||||
storage = Fog::Storage.new(:provider => 'AWS')
|
storage = Fog::Storage.new(:provider => 'AWS')
|
||||||
directory = storage.directories.new(:key => 'fog.io')
|
directory = storage.directories.new(:key => 'fog.io')
|
||||||
|
|
||||||
# write rdoc files to versioned 'folder'
|
# write doc files to versioned 'folder'
|
||||||
Rake::Task[:rdoc].invoke
|
Rake::Task[:yard].invoke
|
||||||
for file_path in Dir.glob('rdoc/**/*')
|
for file_path in Dir.glob("#{YARDOC_LOCATION}/**/*")
|
||||||
next if File.directory?(file_path)
|
next if File.directory?(file_path)
|
||||||
file_name = file_path.gsub('rdoc/', '')
|
file_name = file_path.gsub("#{YARDOC_LOCATION}/", '')
|
||||||
key = '' << version << '/rdoc/' << file_name
|
key = '' << version << "/#{YARDOC_LOCATION}/" << file_name
|
||||||
Formatador.redisplay(' ' * 128)
|
Formatador.redisplay(' ' * 128)
|
||||||
Formatador.redisplay("Uploading [bold]#{key}[/]")
|
Formatador.redisplay("Uploading [bold]#{key}[/]")
|
||||||
directory.files.create(
|
directory.files.create(
|
||||||
|
@ -419,12 +418,12 @@ task :upload_rdoc do
|
||||||
end
|
end
|
||||||
Formatador.redisplay(' ' * 128)
|
Formatador.redisplay(' ' * 128)
|
||||||
directory.files.create(
|
directory.files.create(
|
||||||
:body => redirecter("#{version}/rdoc/index.html"),
|
:body => redirecter("#{version}/#{YARDOC_LOCATION}/index.html"),
|
||||||
:content_type => 'text/html',
|
:content_type => 'text/html',
|
||||||
:key => 'latest/rdoc/index.html',
|
:key => "latest/#{YARDOC_LOCATION}/index.html",
|
||||||
:public => true
|
:public => true
|
||||||
)
|
)
|
||||||
Formatador.redisplay("Uploaded rdoc\n")
|
Formatador.redisplay("Uploaded yardoc\n")
|
||||||
end
|
end
|
||||||
|
|
||||||
def redirecter(path)
|
def redirecter(path)
|
||||||
|
|
|
@ -56,7 +56,7 @@ Gem::Specification.new do |s|
|
||||||
s.add_development_dependency('jekyll')
|
s.add_development_dependency('jekyll')
|
||||||
s.add_development_dependency('rake')
|
s.add_development_dependency('rake')
|
||||||
s.add_development_dependency('rbvmomi')
|
s.add_development_dependency('rbvmomi')
|
||||||
s.add_development_dependency('rdoc')
|
s.add_development_dependency('yard')
|
||||||
s.add_development_dependency('thor')
|
s.add_development_dependency('thor')
|
||||||
s.add_development_dependency('rspec', '~>1.3.1')
|
s.add_development_dependency('rspec', '~>1.3.1')
|
||||||
s.add_development_dependency('rbovirt', '>=0.0.11')
|
s.add_development_dependency('rbovirt', '>=0.0.11')
|
||||||
|
|
Loading…
Reference in New Issue