Class: Rake::DevEiate

Inherits:
TaskLib
  • Object
show all
Includes:
TraceOutput
Defined in:
lib/rake/deveiate.rb

Overview

A task library for maintaining an open-source library.

Constant Summary collapse

VERSION_PATTERN =

Pattern for extracting a version constant

/VERSION\s*=\s*(?<quote>['"])(?<version>\d+(\.\d+){2}.*)\k<quote>/
VERSION =

The version of this library

'0.6.0'
DEFAULT_GEMSERVER =

The server to release to by default

'https://rubygems.org/'
DEFAULT_DESCRIPTION =

The description to use if none is set

"A gem of some sort."
DEFAULT_VERSION =

The version to use if one cannot be read from the source

'0.1.0'
PROJECT_DIR =

Paths

Pathname( '.' )
DOCS_DIR = 
PROJECT_DIR + 'docs'
LIB_DIR = 
PROJECT_DIR + 'lib'
EXT_DIR = 
PROJECT_DIR + 'ext'
SPEC_DIR = 
PROJECT_DIR + 'spec'
INT_SPEC_DIR = 
PROJECT_DIR + 'integration'
DATA_DIR = 
PROJECT_DIR + 'data'
CERTS_DIR = 
PROJECT_DIR + 'certs'
PKG_DIR = 
PROJECT_DIR + 'pkg'
CHECKSUM_DIR = 
PROJECT_DIR + 'checksum'
DEFAULT_MANIFEST_FILE = 
PROJECT_DIR + 'Manifest.txt'
DEFAULT_README_FILE = 
PROJECT_DIR + 'README.md'
DEFAULT_HISTORY_FILE = 
PROJECT_DIR + 'History.md'
DEFAULT_PROJECT_FILES = 
Rake::FileList[
	'*.{rdoc,md,txt}',
	'bin/*',
	'lib/**/*.rb',
	'ext/*.[ch]', 'ext/**/*.[ch]',
	'data/**/*',
	'spec/**/*.rb',
]
DEFAULT_LICENSE =

The default license for the project in SPDX form: spdx.org/licenses

'BSD-3-Clause'
GEMDEPS_FILE =

The file that contains the project’s dependencies

PROJECT_DIR + 'gem.deps.rb'
DOCUMENTATION_SUFFIXES =

The file suffixes to include in documentation

%w[
	.rb
	.c
	.h
	.md
	.rdoc
	.txt
]
DEVEIATE_DATADIR =

The path to the data directory for the Prestigio library.

if ENV['DEVEIATE_DATADIR']
	Pathname( ENV['DEVEIATE_DATADIR'] )
elsif Gem.loaded_specs['rake-deveiate'] &&
      File.directory?( Gem.loaded_specs['rake-deveiate'].datadir )
	Pathname( Gem.loaded_specs['rake-deveiate'].datadir )
else
	Pathname( __FILE__ ).dirname.parent.parent + 'data/rake-deveiate'
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, **options, &block) ⇒ DevEiate

Create the devEiate tasks for a gem with the given name.



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/rake/deveiate.rb', line 127

def initialize( name, **options, &block )
	@name          = validate_gemname( name )
	@options       = options

	@manifest_file = DEFAULT_MANIFEST_FILE.dup
	@project_files = self.read_manifest
	@version       = self.find_version || DEFAULT_VERSION
	@readme_file   = self.find_readme
	@history_file  = self.find_history_file
	@readme        = self.parse_readme
	@rdoc_files    = self.make_rdoc_filelist
	@cert_files    = Rake::FileList[ CERTS_DIR + '*.pem' ]
	@licenses      = [ DEFAULT_LICENSE ]

	@docs_dir      = DOCS_DIR.dup

	@title         = self.extract_default_title
	@authors       = self.extract_authors
	@homepage      = self.extract_homepage
	@description   = self.extract_description || DEFAULT_DESCRIPTION
	@summary       = nil
	@dependencies  = self.find_dependencies

	@publish_to    = nil

	super()

	self.load_task_libraries

	if block
		if block.arity.nonzero?
			block.call( self )
		else
			self.instance_exec( self, &block )
		end
	end
end

Instance Attribute Details

#allowed_push_host ⇒ Object

The gemserver to push gems to



242
243
244
 
# File 'lib/rake/deveiate.rb', line 242

def allowed_push_host
  @allowed_push_host
end

#authors ⇒ Object

The gem’s authors in the form of strings in the format: ‘Name <email>`



230
231
232
 
# File 'lib/rake/deveiate.rb', line 230

def authors
  @authors
end

#cert_files ⇒ Object

The public cetificates that can be used to verify signed gems



221
222
223
 
# File 'lib/rake/deveiate.rb', line 221

def cert_files
  @cert_files
end

#dependencies ⇒ Object

The Gem::RequestSet that describes the gem’s dependencies



238
239
240
 
# File 'lib/rake/deveiate.rb', line 238

def dependencies
  @dependencies
end

#description ⇒ Object

The descriotion of the gem



180
181
182
 
# File 'lib/rake/deveiate.rb', line 180

def description
  @description
end

#homepage ⇒ Object

The URI of the project’s homepage as a String



234
235
236
 
# File 'lib/rake/deveiate.rb', line 234

def homepage
  @homepage
end

#licenses ⇒ Object

The licenses the project is distributed under; usual practice is to list the SPDX name: spdx.org/licenses



226
227
228
 
# File 'lib/rake/deveiate.rb', line 226

def licenses
  @licenses
end

#name ⇒ Object (readonly)

The name of the gem the task will build



172
173
174
 
# File 'lib/rake/deveiate.rb', line 172

def name
  @name
end

#options ⇒ Object (readonly)

The options Hash the task lib was created with



176
177
178
 
# File 'lib/rake/deveiate.rb', line 176

def options
  @options
end

#project_files ⇒ Object

The files which should be distributed with the project as a Rake::FileList



213
214
215
 
# File 'lib/rake/deveiate.rb', line 213

def project_files
  @project_files
end

#publish_to ⇒ Object

The rsync-compatible target to publish documentation to.



246
247
248
 
# File 'lib/rake/deveiate.rb', line 246

def publish_to
  @publish_to
end

#rdoc_files ⇒ Object

The files which should be used to generate documentation as a Rake::FileList



217
218
219
 
# File 'lib/rake/deveiate.rb', line 217

def rdoc_files
  @rdoc_files
end

#readme ⇒ Object

The README of the project as an RDoc::Markup::Document



193
194
195
 
# File 'lib/rake/deveiate.rb', line 193

def readme
  @readme
end

#summary ⇒ Object

The summary description of the gem.



184
185
186
 
# File 'lib/rake/deveiate.rb', line 184

def summary
  @summary
end

#title ⇒ Object

The title of the library for things like docs, gemspec, etc.



197
198
199
 
# File 'lib/rake/deveiate.rb', line 197

def title
  @title
end

#version ⇒ Object (readonly)

The Gem::Version of the current library, extracted from the top-level namespace.



189
190
191
 
# File 'lib/rake/deveiate.rb', line 189

def version
  @version
end

Class Method Details

.attr_pathname(name) ⇒ Object

Declare an attribute that should be cast to a Pathname when set.



109
110
111
112
113
114
 
# File 'lib/rake/deveiate.rb', line 109

def self::attr_pathname( name ) # :nodoc:
	attr_reader( name )
	define_method( "#{name}=" ) do |new_value|
		instance_variable_set( "@#{name}", Pathname(new_value) )
	end
end

.setup(name, **options, &block) ⇒ Object

Set up common development tasks



118
119
120
121
122
 
# File 'lib/rake/deveiate.rb', line 118

def self::setup( name, **options, &block )
	tasklib = self.new( name, **options, &block )
	tasklib.define_tasks
	return tasklib
end

Instance Method Details

#author_names ⇒ Object

Return just the name parts of the library’s authors setting.



396
397
398
399
400
 
# File 'lib/rake/deveiate.rb', line 396

def author_names
	return self.authors.map do |author|
		author[ /^(.*?) </, 1 ]
	end
end

#default_manifest ⇒ Object

Return the Rake::FileList that’s used in lieu of the manifest file if it isn’t present.



486
487
488
 
# File 'lib/rake/deveiate.rb', line 486

def default_manifest
	return DEFAULT_PROJECT_FILES.dup
end

#define_debug_tasks ⇒ Object

Set up tasks for debugging the task library.



328
329
330
331
332
333
334
335
336
 
# File 'lib/rake/deveiate.rb', line 328

def define_debug_tasks
	task( :base_debug ) do
		self.output_documentation_debugging
		self.output_project_files_debugging
		self.output_dependency_debugging
	end

	task :debug => :base_debug
end

#define_default_tasks ⇒ Object

Set up a simple default task



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/rake/deveiate.rb', line 292

def define_default_tasks
	desc "The task that runs by default"
	task( :default => :spec )

	desc "Check in the current changes"
	task :checkin => [ :precheckin, :check, :test ]
	task :commit => :checkin
	task :ci => :checkin
	task :precheckin

	desc "Sanity-check the project"
	task :check

	desc "Update the history file"
	task :update_history

	desc "Package up and push a release"
	task :release => [ :prerelease, :release_gem, :postrelease ]
	task :prerelease
	task :release_gem
	task :postrelease

	desc "Run all the project's tests"
	task :test
	task :spec
	task :integration

	desc "Set up the project for development"
	task :setup do
		self.install_dependencies
	end

end

#define_tasks ⇒ Object

Task-definition hook.



283
284
285
286
287
288
 
# File 'lib/rake/deveiate.rb', line 283

def define_tasks
	self.define_default_tasks
	self.define_debug_tasks

	super if defined?( super )
end

#extract_authors ⇒ Object

Extract authors in the form ‘Firstname Lastname <email@address>` from the README.



404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/rake/deveiate.rb', line 404

def extract_authors
	readme = self.readme or return []
	content = readme.parts.grep_v( RDoc::Markup::BlankLine )

	heading, list = content.each_cons( 2 ).find do |heading, list|
		heading.is_a?( RDoc::Markup::Heading ) && heading.text =~ /^authors?/i &&
			list.is_a?( RDoc::Markup::List )
	end

	unless list
		self.trace "Couldn't find an Author(s) section of the readme."
		return []
	end

	return list.items.map do |item|
		# unparse the name + email
		raw = item.parts.first.text or next
		name, email = raw.split( ' mailto:', 2 )
		if email
			"%s <%s>" % [ name, email ]
		else
			name
		end
	end
end

#extract_default_title ⇒ Object

Extract the default title from the README if possible, or derive it from the gem name.



375
376
377
378
379
 
# File 'lib/rake/deveiate.rb', line 375

def extract_default_title
	return self.name unless self.readme&.table_of_contents&.first
	title = self.readme.table_of_contents.first.text
	title ||= self.name
end

#extract_description ⇒ Object

Extract a description from the README if possible. Returns nil if not.



389
390
391
392
 
# File 'lib/rake/deveiate.rb', line 389

def extract_description
	parts = self.readme&.parts or return nil
	return parts.find {|part| part.is_a?(RDoc::Markup::Paragraph) }&.text
end

#extract_homepage ⇒ Object

Extract the URI of the homepage from the ‘home` item of the first NOTE-type list in the README. Returns nil if no such URI could be found.



433
434
435
436
437
438
439
440
441
442
 
# File 'lib/rake/deveiate.rb', line 433

def extract_homepage
	return fail_extraction( :homepage, "no README" ) unless self.readme

	list = self.readme.parts.find {|part| RDoc::Markup::List === part && part.type == :NOTE } or
		return fail_extraction(:homepage, "No NOTE list")
	item = list.items.find {|item| item.label.include?('home') } or
		return fail_extraction(:homepage, "No `home` item")

	return item.parts.first.text
end

#extract_summary ⇒ Object

Extract a summary from the README if possible. Returns nil if not.



383
384
385
 
# File 'lib/rake/deveiate.rb', line 383

def extract_summary
	return self.description.split( /(?<=\.)\s+/ ).first.gsub( /\n/, ' ' )
end

#find_dependencies ⇒ Object

Load the gemdeps file if it exists, and return a Gem::RequestSet with the regular dependencies contained in it.



582
583
584
585
586
587
588
589
590
591
592
 
# File 'lib/rake/deveiate.rb', line 582

def find_dependencies
	unless GEMDEPS_FILE.readable?
		self.prompt.warn "Deps file (%s) is missing or unreadable, assuming no dependencies." %
			[ GEMDEPS_FILE ]
		return []
	end

	finder = Rake::DevEiate::GemDepFinder.new( GEMDEPS_FILE )
	finder.load
	return finder.dependencies
end

#find_history_file ⇒ Object

Find the history file in the list of project files and return it as a Pathname.



519
520
521
522
523
524
525
526
527
 
# File 'lib/rake/deveiate.rb', line 519

def find_history_file
	file = self.project_files.find {|file| file =~ /^History\.(md|rdoc)$/ }
	if file
		return Pathname( file )
	else
		self.prompt.warn "No History.{md,rdoc} found in the project files."
		return DEFAULT_HISTORY_FILE
	end
end

#find_readme ⇒ Object

Find the README file in the list of project files and return it as a Pathname.



506
507
508
509
510
511
512
513
514
 
# File 'lib/rake/deveiate.rb', line 506

def find_readme
	file = self.project_files.find {|file| file =~ /^README\.(md|rdoc)$/ }
	if file
		return Pathname( file )
	else
		self.prompt.warn "No README found in the project files."
		return DEFAULT_README_FILE
	end
end

#find_version ⇒ Object

Find the file that contains the VERSION constant and return it as a Gem::Version.



447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'lib/rake/deveiate.rb', line 447

def find_version
	version_file = LIB_DIR + "%s.rb" % [ self.name.gsub(/-/, '/') ]

	unless version_file.readable?
		self.prompt.warn "Version could not be read from %s" % [ version_file ]
		return nil
	end

	version_line = version_file.readlines.find {|l| l =~ VERSION_PATTERN } or
		abort "Can't read the VERSION from #{version_file}!"
	version = version_line[ VERSION_PATTERN, :version ] or
		abort "Couldn't find a semantic version in %p" % [ version_line ]

	return Gem::Version.new( version )
end

#generate_dependencies_table ⇒ Object

Generate a TTY::Table from the current dependency list and return it.



554
555
556
557
558
559
560
561
562
 
# File 'lib/rake/deveiate.rb', line 554

def generate_dependencies_table
	table = TTY::Table.new( header: ['Gem', 'Version', 'Type'] )

	self.dependencies.each do |dep|
		table << [ dep.name, dep.requirement.to_s, dep.type ]
	end

	return table
end

#generate_project_files_table ⇒ Object

Generate a TTY::Table from the current project files and return it.



531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
 
# File 'lib/rake/deveiate.rb', line 531

def generate_project_files_table
	columns = [
		self.project_files.sort,
		self.rdoc_files.sort
	]

	max_length = columns.map( &:length ).max
	columns.each do |col|
		self.trace "Filling out columns %d-%d" % [ col.length, max_length ]
		next if col.length == max_length
		col.fill( '', col.length .. max_length - 1 )
	end

	table = TTY::Table.new(
		header: ['Project', 'Documentation'],
		rows: columns.transpose,
	)

	return table
end

#has_manifest? ⇒ Boolean

Returns true if the manifest file exists and is readable.

Returns:

  • (Boolean) 


465
466
467
 
# File 'lib/rake/deveiate.rb', line 465

def has_manifest?
	return self.manifest_file.readable?
end

#header_char_for(filename) ⇒ Object

Return the character used to build headings give the filename of the file to be generated.



603
604
605
606
607
608
609
610
 
# File 'lib/rake/deveiate.rb', line 603

def header_char_for( filename )
	case File.extname( filename )
	when '.md' then return '#'
	when '.rdoc' then return '='
	else
		raise "Don't know what header character is appropriate for %s" % [ filename ]
	end
end

#history_file ⇒ Object

The file that provides high-level change history



205
 
# File 'lib/rake/deveiate.rb', line 205

attr_pathname :history_file

#indent(text, spaces = 4) ⇒ Object

Return a copy of the given text prefixed by spaces number of spaces.



687
688
689
690
 
# File 'lib/rake/deveiate.rb', line 687

def indent( text, spaces=4 )
	prefix = ' ' * spaces
	return text.gsub( /(?<=\A|\n)/m, prefix )
end

#install_dependencies ⇒ Object

Install the gems listed in the gem dependencies file.



596
597
598
 
# File 'lib/rake/deveiate.rb', line 596

def install_dependencies
	ruby '-S', 'gem', 'i', '-Ng'
end

#load_and_render_template(template_path, target_filename) ⇒ Object

Load the template at the specified template_path, and render it with suitable settings for the given target_filename.



626
627
628
629
630
631
632
633
634
 
# File 'lib/rake/deveiate.rb', line 626

def load_and_render_template( template_path, target_filename )
	template = self.read_template( template_path )
	header_char = self.header_char_for( target_filename )

	return template.result_with_hash(
		header_char: header_char,
		project: self
	)
end

#load_task_libraries ⇒ Object

Load the deveiate task libraries.



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/rake/deveiate.rb', line 254

def load_task_libraries
	taskdir = Pathname( __FILE__.delete_suffix('.rb') )
	tasklibs = Rake::FileList[ taskdir + '*.rb' ].pathmap( '%-2d/%n' )

	self.trace( "Loading task libs: %p" % [ tasklibs ] )
	tasklibs.each do |lib|
		require( lib )
	end

	self.class.constants.
		map {|c| self.class.const_get(c) }.
		select {|c| c.respond_to?(:instance_methods) }.
		select {|c| c.instance_methods(false).include?(:define_tasks) }.
		each do |mod|
			self.trace "Loading tasks from %p" % [ mod ]
			extend( mod )
		end

	self.setup( self.name, **self.options )
end

#make_rdoc_filelist ⇒ Object

Make a Rake::FileList of the files that should be used to generate documentation.



493
494
495
496
497
498
499
500
501
 
# File 'lib/rake/deveiate.rb', line 493

def make_rdoc_filelist
	list = self.project_files.dup

	list.exclude do |fn|
		fn =~ %r:^(spec|data)/: || !fn.end_with?( *DOCUMENTATION_SUFFIXES )
	end

	return list
end

#manifest_file ⇒ Object

The file to read the list of distribution files from



209
 
# File 'lib/rake/deveiate.rb', line 209

attr_pathname :manifest_file

#output_dependency_debugging ⇒ Object

Output debugging about the project’s dependencies.



674
675
676
677
678
679
680
681
682
683
 
# File 'lib/rake/deveiate.rb', line 674

def output_dependency_debugging
	self.prompt.say( "Dependencies", color: :bright_green )
	table = self.generate_dependencies_table
	if table.empty?
		self.prompt.warn( "None." )
	else
		self.prompt.say( table.render(:unicode, padding: [0,1]) )
	end
	self.prompt.say( "\n" )
end

#output_documentation_debugging ⇒ Object

Output debugging information about documentation.



638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
 
# File 'lib/rake/deveiate.rb', line 638

def output_documentation_debugging
	summary = self.extract_summary
	description = self.extract_description
	homepage = self.extract_homepage

	self.prompt.say( "Documentation", color: :bright_green )
	self.prompt.say( "Authors:" )
	self.authors.each do |author|
		self.prompt.say( " • " )
		self.prompt.say( author, color: :bold )
	end
	self.prompt.say( "Summary: " )
	self.prompt.say( summary, color: :bold )
	self.prompt.say( "Description:" )
	self.prompt.say( description, color: :bold )
	self.prompt.say( "Homepage:" )
	self.prompt.say( homepage, color: :bold )
	self.prompt.say( "\n" )
end

#output_project_files_debugging ⇒ Object

Output debugging info related to the list of project files the build operates on.



661
662
663
664
665
666
667
668
669
670
 
# File 'lib/rake/deveiate.rb', line 661

def output_project_files_debugging
	self.prompt.say( "Project files:", color: :bright_green )
	table = self.generate_project_files_table
	if table.empty?
		self.prompt.warn( "None." )
	else
		self.prompt.say( table.render(:unicode, padding: [0,1]) )
	end
	self.prompt.say( "\n" )
end

#parse_readme ⇒ Object

Parse the README into an RDoc::Markup::Document and return it



566
567
568
569
570
571
572
573
574
575
576
577
 
# File 'lib/rake/deveiate.rb', line 566

def parse_readme
	return nil unless self.readme_file.readable?

	case self.readme_file.extname
	when '.md'
		return RDoc::Markdown.parse( self.readme_file.read )
	when '.rdoc'
		return RDoc::Markup.parse( self.readme_file.read )
	else
		raise "Can't parse %s: unhandled format %p" % [ self.readme_file, README_FILE.extname ]
	end
end

#pastel ⇒ Object

Fetch the Pastel object, creating it if necessary.



350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/rake/deveiate.rb', line 350

def pastel
	return @pastel ||= begin
		pastel = Pastel.new( enabled: $stdout.tty? )
		pastel.alias_color( :headline, :bold, :white, :on_black )
		pastel.alias_color( :success, :bold, :green )
		pastel.alias_color( :error, :bold, :red )
		pastel.alias_color( :warning, :yellow )
		pastel.alias_color( :added, :green )
		pastel.alias_color( :removed, :red )
		pastel.alias_color( :prompt, :cyan )
		pastel.alias_color( :even_row, :bold )
		pastel.alias_color( :odd_row, :reset )
		pastel
	end
end

#prompt ⇒ Object

Fetch the TTY-Prompt, creating it if necessary.



344
345
346
 
# File 'lib/rake/deveiate.rb', line 344

def prompt
	return @prompt ||= TTY::Prompt.new( output: $stderr )
end

#read_manifest ⇒ Object

Read the manifest file if there is one, falling back to a default list if there isn’t a manifest.



472
473
474
475
476
477
478
479
480
481
 
# File 'lib/rake/deveiate.rb', line 472

def read_manifest
	if self.has_manifest?
		entries = self.manifest_file.readlines.map( &:chomp )
		return Rake::FileList[ *entries ]
	else
		self.prompt.warn "No manifest (%s): falling back to a default list" %
			[ self.manifest_file ]
		return self.default_manifest
	end
end

#read_template(name) ⇒ Object

Read a template with the given name from the data directory and return it as an ERB object.



615
616
617
618
619
620
621
 
# File 'lib/rake/deveiate.rb', line 615

def read_template( name )
	name = "%s.erb" % [ name ] unless name.to_s.end_with?( '.erb' )
	template_path = DEVEIATE_DATADIR + name
	template_src = template_path.read( encoding: 'utf-8' )

	return ERB.new( template_src, trim_mode: '-' )
end

#readme_file ⇒ Object

The file that will be the main page of documentation



201
 
# File 'lib/rake/deveiate.rb', line 201

attr_pathname :readme_file

#setup(name, **options) ⇒ Object

Post-loading callback.



277
278
279
 
# File 'lib/rake/deveiate.rb', line 277

def setup( name, **options )
	# No-op
end

#trace(*args) ⇒ Object

Output args to $stderr if tracing is enabled.



368
369
370
 
# File 'lib/rake/deveiate.rb', line 368

def trace( *args )
	Rake.application.trace( *args ) if Rake.application.options.trace
end