Class: RDoc::Generator::Fivefish
- Inherits:
-
Object
- Object
- RDoc::Generator::Fivefish
- Extended by:
- Loggability
- Includes:
- FileUtils
- Defined in:
- lib/rdoc/generator/fivefish.rb
Overview
The Fivefish generator class.
Constant Summary collapse
- DATADIR =
The data directory in the project if that exists, otherwise the gem datadir
if ENV['FIVEFISH_DATADIR'] Pathname( ENV['FIVEFISH_DATADIR'] ).( Pathname.pwd ) elsif File.directory?( 'data/rdoc-generator-fivefish' ) Pathname( 'data/rdoc-generator-fivefish' ).( Pathname.pwd ) elsif path = Gem.datadir('rdoc-generator-fivefish') Pathname( path ) else raise ScriptError, "can't find the data directory!" end
Instance Attribute Summary collapse
-
#base_dir ⇒ Object
readonly
The base directory (current working directory) as a Pathname.
-
#options ⇒ Object
readonly
The command-line options given to the rdoc command.
-
#output_dir ⇒ Object
readonly
The output directory as a Pathname.
-
#store ⇒ Object
readonly
The RDoc::Store that contains the parsed CodeObjects.
-
#template_dir ⇒ Object
readonly
The directory containing templates as a Pathname.
Class Method Summary collapse
-
.setup_options(rdoc_options) ⇒ Object
Add generator-specific options to the option-parser.
Instance Method Summary collapse
-
#class_dir ⇒ Object
(also: #file_dir)
Backward-compatible (no-op) method.
-
#copy_static_assets ⇒ Object
Copies static files from the static_path into the output directory.
-
#debug_msg(*msg) ⇒ Object
Output progress information if debugging is enabled.
-
#gen_sub_directories ⇒ Object
Create the directories the generated docs will live in if they don’t already exist.
-
#generate ⇒ Object
Build the initial indices and output objects based on the files in the generator’s store.
-
#generate_class_files ⇒ Object
Generate a documentation file for each class and module.
-
#generate_file_files ⇒ Object
Generate a documentation file for each file.
-
#generate_index_page ⇒ Object
Generate an index page which lists all the classes which are documented.
-
#generate_search_index ⇒ Object
Generate a JSON search index for the quicksearch blank.
-
#initialize(store, options) ⇒ Fivefish
constructor
Set up some instance variables.
-
#populate_data_objects ⇒ Object
Populate the data objects necessary to generate documentation from the generator’s #store.
Constructor Details
#initialize(store, options) ⇒ Fivefish
Set up some instance variables
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
# File 'lib/rdoc/generator/fivefish.rb', line 58 def initialize( store, ) @store = store = $DEBUG_RDOC = $VERBOSE || $DEBUG self.log.debug "Setting up generator for %p with options: %p" % [ @store, ] extend( FileUtils::Verbose ) if $DEBUG_RDOC extend( FileUtils::DryRun ) if .dry_run @base_dir = Pathname.pwd. @template_dir = DATADIR @output_dir = Pathname( .op_dir ).( @base_dir ) @template_cache = {} @files = nil @classes = nil @search_index = {} Inversion::Template.configure( :template_paths => [self.template_dir + 'templates'] ) end |
Instance Attribute Details
#base_dir ⇒ Object (readonly)
The base directory (current working directory) as a Pathname
86 87 88 |
# File 'lib/rdoc/generator/fivefish.rb', line 86 def base_dir @base_dir end |
#options ⇒ Object (readonly)
The command-line options given to the rdoc command
95 96 97 |
# File 'lib/rdoc/generator/fivefish.rb', line 95 def end |
#output_dir ⇒ Object (readonly)
The output directory as a Pathname
92 93 94 |
# File 'lib/rdoc/generator/fivefish.rb', line 92 def output_dir @output_dir end |
#store ⇒ Object (readonly)
The RDoc::Store that contains the parsed CodeObjects
98 99 100 |
# File 'lib/rdoc/generator/fivefish.rb', line 98 def store @store end |
#template_dir ⇒ Object (readonly)
The directory containing templates as a Pathname
89 90 91 |
# File 'lib/rdoc/generator/fivefish.rb', line 89 def template_dir @template_dir end |
Class Method Details
.setup_options(rdoc_options) ⇒ Object
Add generator-specific options to the option-parser
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
# File 'lib/rdoc/generator/fivefish.rb', line 40 def self::( ) op = .option_parser op.accept( URI ) do |string| uri = URI.parse( string ) rescue nil raise OptionParser::InvalidArgument unless uri uri end op.on( '--additional-stylesheet=URL', URI, "Add an additional (preferred) stylesheet", "link to each generated page. This allows", "the output style to be overridden." ) do |url| .additional_stylesheet = url end end |
Instance Method Details
#class_dir ⇒ Object Also known as: file_dir
Backward-compatible (no-op) method.
109 110 111 |
# File 'lib/rdoc/generator/fivefish.rb', line 109 def class_dir # :nodoc: nil end |
#copy_static_assets ⇒ Object
Copies static files from the static_path into the output directory
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 |
# File 'lib/rdoc/generator/fivefish.rb', line 263 def copy_static_assets asset_paths = self.find_static_assets self.log.debug "Copying assets from paths: %s" % [ asset_paths.join(', ') ] asset_paths.each do |path| # For plain files, just install them if path.file? self.log.debug " plain file; installing as-is" install( path, self.output_dir, :mode => 0644 ) # Glob all the files out of subdirectories and install them elsif path.directory? self.log.debug " directory %p; copying contents" % [ path ] Pathname.glob( path + '{css,fonts,img,js}/**/*'.to_s ).each do |asset| next if asset.directory? || asset.basename.to_s.start_with?( '.' ) dst = asset.relative_path_from( path ) dst.dirname.mkpath self.log.debug " %p -> %p" % [ asset, dst ] install asset, dst, :mode => 0644 end end end end |
#debug_msg(*msg) ⇒ Object
Output progress information if debugging is enabled
102 103 104 105 |
# File 'lib/rdoc/generator/fivefish.rb', line 102 def debug_msg( *msg ) return unless $DEBUG_RDOC $stderr.puts( *msg ) end |
#gen_sub_directories ⇒ Object
Create the directories the generated docs will live in if they don’t already exist.
117 118 119 |
# File 'lib/rdoc/generator/fivefish.rb', line 117 def gen_sub_directories self.output_dir.mkpath end |
#generate ⇒ Object
Build the initial indices and output objects based on the files in the generator’s store.
123 124 125 126 127 128 129 130 131 132 133 |
# File 'lib/rdoc/generator/fivefish.rb', line 123 def generate self.populate_data_objects self.generate_index_page self.generate_class_files self.generate_file_files self.generate_search_index self.copy_static_assets end |
#generate_class_files ⇒ Object
Generate a documentation file for each class and module
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 |
# File 'lib/rdoc/generator/fivefish.rb', line 176 def generate_class_files layout = self.load_layout_template template = self.load_template( 'class.tmpl' ) self.log.debug "Generating class documentation in #{self.output_dir}" @classes.each do |klass| self.log.debug " working on %s (%s)" % [klass.full_name, klass.path] out_file = self.output_dir + klass.path out_file.dirname.mkpath template.klass = klass layout.contents = template layout.rel_prefix = self.output_dir.relative_path_from( out_file.dirname ) layout.pageclass = 'class-page' out_file.open( 'w', 0644 ) {|io| io.print(layout.render) } end end |
#generate_file_files ⇒ Object
Generate a documentation file for each file
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 |
# File 'lib/rdoc/generator/fivefish.rb', line 200 def generate_file_files layout = self.load_layout_template template = self.load_template( 'file.tmpl' ) self.log.debug "Generating file documentation in #{self.output_dir}" @files.select {|f| f.text? }.each do |file| out_file = self.output_dir + file.path out_file.dirname.mkpath self.log.debug " working on %s (%s)" % [file.full_name, out_file] template.file = file # If the page itself has an H1, use it for the header, otherwise make one # out of the name of the file if md = file.description.match( %r{<h1.*?>.*?</h1>}i ) template.header = md[ 0 ] template.description = file.description[ md.offset(0)[1] + 1 .. -1 ] else template.header = File.basename( file.full_name, File.extname(file.full_name) ) template.description = file.description end layout.contents = template layout.rel_prefix = self.output_dir.relative_path_from(out_file.dirname) layout.pageclass = 'file-page' out_file.open( 'w', 0644 ) {|io| io.print(layout.render) } end end |
#generate_index_page ⇒ Object
Generate an index page which lists all the classes which are documented.
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 |
# File 'lib/rdoc/generator/fivefish.rb', line 147 def generate_index_page self.log.debug "Generating index page" layout = self.load_layout_template template = self.load_template( 'index.tmpl' ) out_file = self.output_dir + 'index.html' out_file.dirname.mkpath mainpage = nil if mpname = self..main_page mainpage = @files.find {|f| f.full_name == mpname } else mainpage = @files.find {|f| f.full_name =~ /\breadme\b/i } end self.log.debug " using main_page (%s)" % [ mainpage ] if mainpage template.mainpage = mainpage template.synopsis = self.extract_synopsis( mainpage ) end layout.rel_prefix = self.output_dir.relative_path_from( out_file.dirname ) layout.contents = template layout.pageclass = 'index-page' out_file.open( 'w', 0644 ) {|io| io.print(layout.render) } end |
#generate_search_index ⇒ Object
Generate a JSON search index for the quicksearch blank.
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 |
# File 'lib/rdoc/generator/fivefish.rb', line 234 def generate_search_index out_file = self.output_dir + 'js/searchindex.js' self.log.debug "Generating search index (%s)." % [ out_file ] index = [] objs = self.get_indexable_objects objs.each do |codeobj| self.log.debug " #{codeobj.name}..." record = codeobj.search_record index << { name: record[2], link: record[4], snippet: record[6], type: codeobj.class.name.downcase.sub( /.*::/, '' ) } end self.log.debug " dumping JSON..." out_file.dirname.mkpath ofh = out_file.open( 'w:utf-8', 0644 ) json = Yajl.dump( index, pretty: true, indent: "\t" ) ofh.puts( 'var SearchIndex = ', json, ';' ) end |
#populate_data_objects ⇒ Object
Populate the data objects necessary to generate documentation from the generator’s #store.
138 139 140 141 142 143 |
# File 'lib/rdoc/generator/fivefish.rb', line 138 def populate_data_objects @files = self.store.all_files.sort @classes = self.store.all_classes_and_modules.sort @methods = @classes.map {|m| m.method_list }.flatten.sort @modsort = self.get_sorted_module_list( @classes ) end |