[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
|
||||
.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/*
|
||||
|
|
37
Rakefile
37
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)
|
||||
|
|
|
@ -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')
|
||||
|
|
Loading…
Reference in New Issue