YARD plugin for hoe.
### Tasks Provided:
yard: Generate YARD documentation
docs: Generate YARD documentation
hoe-yard version
File extensions for various markups
Supported markups
File extensions indicating raw content
Markup style used in documentation, like textile, markdown or rdoc. (default: `:rdoc`)
Overrides the library used to process markup formatting (specify the gem name)
Options to pass to YARD
Title for the YARD documentation
Defines additional rake tasks.
# File lib/hoe/yard.rb, line 78 def define_yard_tasks require 'yard' desc "Remove YARD products" task :clobber_docs do if File.exists?(local_yard_dir) rm_r local_yard_dir, :verbose => true end end # generate the YARD options opts = normalize_yard_opts # define the yard task ::YARD::Rake::YardocTask.new do |t| t.files = self.spec.files.select { |path| path =~ /^lib\/.+\.rb$/ } t.options = opts + ['--files'] + self.yard_files end task :docs => :yard # override the RDoc options self.spec.rdoc_options = opts end
Initializes the hoe-yard plugin.
# File lib/hoe/yard.rb, line 48 def initialize_yard self.yard_title = Hoe.normalize_names(self.name).last + ' Documentation' self.yard_markup = nil self.yard_markup_provider = nil self.yard_options = [] # find the README.* and History.* files self.readme_file = intuit_file_name(File.basename(self.readme_file)) self.history_file = intuit_file_name(File.basename(self.history_file)) # disable RDoc and ri tasks self.need_rdoc = false unless self.name == 'hoe-yard' # add hoe-yard as a development dependency self.extra_dev_deps << ['hoe-yard', ">=#{PLUGIN_VERSION}"] end # we have YARD docs self.spec_extras.merge!(:has_rdoc => 'yard') if self.history_file # include the history file self.yard_files << self.history_file end end
Intuitively finds the file with the given name, using the current YARD markup setting to guess the file extension.
@param [String] name
The given file name.
@return [String]
The file sharing the same name, but ending with the appropriate markup file extension.
# File lib/hoe/yard.rb, line 199 def intuit_file_name(name) name = name.gsub(/\.[^\.]+$/,'') paths = Dir["#{name}.*"] exts = if self.yard_markup YARD_EXTS[self.yard_markup] else YARD_EXTS.values.flatten.uniq end # append the other raw extensions exts += YARD_RAW_EXTS paths.each do |path| return path if exts.include?(File.extname(path)) end warn "Could not intuitively find the #{name} file" if $DEBUG return nil end
Alias to `Hoe#local_rdoc_dir`.
@return [String]
Relative path to the locally generated documentation directory.
# File lib/hoe/yard.rb, line 150 def local_yard_dir self.local_rdoc_dir end
Alias to `Hoe#local_yard_dir=`.
@param [String] new_dir
New relative path to the locally generated documentation directory.
@return [String]
# File lib/hoe/yard.rb, line 162 def local_yard_dir=(new_dir) self.local_rdoc_dir = new_dir end
Generates the minimal amount of YARD options based on the YARD settings.
@return [Array<String>]
# File lib/hoe/yard.rb, line 226 def normalize_yard_opts opts = self.yard_opts.dup opts << '--title' << self.yard_title if self.yard_markup opts << '--markup' << self.yard_markup end if self.yard_markup_provider opts << '--markup-provider' << self.yard_markup_provider end unless (opts.include?('--quiet') || opts.include?('--verbose') || $DEBUG) opts << '--quiet' end return opts end
Alias to `Hoe#remote_rdoc_dir`.
@return [String]
Relative path to the desired remote documentation directory.
# File lib/hoe/yard.rb, line 172 def remote_yard_dir self.remote_rdoc_dir end
Alias to `Hoe#remote_rdoc_dir=`.
@param [String] new_dir
New relative path to the desired remote documentation directory.
@return [String]
# File lib/hoe/yard.rb, line 184 def remote_yard_dir=(new_dir) self.remote_rdoc_dir = new_dir end
Alias to `Hoe#extra_rdoc_files`.
@return [Array<String>]
Additional files to include in the generated documentation.
# File lib/hoe/yard.rb, line 128 def yard_files self.extra_rdoc_files end
Alias to `Hoe#extra_rdoc_files=`.
@param [Array<String>] new_files
Additional files to include in the generated documentation.
@return [Array<String>]
# File lib/hoe/yard.rb, line 140 def yard_files=(new_files) self.extra_rdoc_files = new_files end
Alias to `#yard_options`.
@deprecated Use `#yard_options` instead.
# File lib/hoe/yard.rb, line 109 def yard_opts self.yard_options end
Alias to `#yard_options=`.
@deprecated Use `#yard_options=` instead.
# File lib/hoe/yard.rb, line 118 def yard_opts=(new_opts) self.yard_options = new_opts end