yard_ghurt 1.2.0 → 1.2.2

data/lib/yard_ghurt/ghp_sync_task.rb

@@ -1,115 +1,83 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019 Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 require 'rake'
-
 require 'rake/tasklib'
-
 require 'yard_ghurt/util'
 
 module YardGhurt
-  ###
   # Sync YARDoc to a local GitHub Pages repo (uses +rsync+ by default).
-  # 
+  #
   # @example What I Use
-  #   YardGhurt::GHPSyncTask.new() do |task|
+  #   YardGhurt::GHPSyncTask.new do |task|
   #     task.ghp_dir = '../esotericpig.github.io/docs/yard_ghurt/yardoc'
   #     task.sync_args << '--delete-after'
   #   end
-  # 
-  # @example Using All Options
-  #   # Execute: rake ghp_doc[false,'Ruby']
-  #   YardGhurt::GHPSyncTask.new(:ghp_doc) do |task|
-  #     task.arg_names   << :name                      # Custom args
-  #     task.deps        << :yard                      # Custom dependencies
-  #     task.description  = 'Rsync my_doc/ to my page'
-  #     task.doc_dir      = 'my_doc'                   # YARDoc directory of generated files
-  #     task.ghp_dir      = '../dest_dir/my_page'
-  #     task.strict       = true                       # Fail if doc_dir doesn't exist
-  #     task.sync_args   << '--delete-after'
-  #     task.sync_cmd     = '/usr/bin/rsync'
-  #     
-  #     task.before = Proc.new() {|task,args| puts "Hi, #{args.name}!"}
-  #     task.after  = Proc.new() {|task,args| puts "Goodbye, #{args.name}!"}
-  #   end
-  # 
-  # @author Jonathan Bradley Whited (@esotericpig)
-  # @since  1.1.0
-  ###
+  #
+  # @since 1.1.0
   class GHPSyncTask < Rake::TaskLib
     # @return [Proc,nil] the Proc ( +respond_to?(:call)+ ) to call at the end of this task or +nil+;
     #                    default: +nil+
     attr_accessor :after
-    
+
     # @note +:deploy+ will be added no matter what (cannot be deleted)
-    # 
+    #
     # @return [Array<Symbol>,Symbol] the custom arg(s) for this task; default: +[:deploy]+
     attr_accessor :arg_names
-    
+
     # @return [Proc,nil] the Proc ( +respond_to?(:call)+ ) to call at the beginning of this task or +nil+;
     #                    default: +nil+
     attr_accessor :before
-    
+
     # @example
     #   task.deps = :yard
     #   # or...
     #   task.deps = [:yard,:yard_gfm_fix]
-    # 
+    #
     # @return [Array<Symbol>,Symbol] the custom dependencies for this task; default: +[]+
     attr_accessor :deps
-    
+
     # @return [String] the description of this task (customizable)
     attr_accessor :description
-    
+
     # @return [String] the source directory of generated YARDoc files; default: +doc+
     attr_accessor :doc_dir
-    
+
     # @note You must set this, else an error is thrown.
-    # 
+    #
     # @return [String] the destination directory to sync {doc_dir} to
     attr_accessor :ghp_dir
-    
+
     # @return [String] the name of this task (customizable); default: +yard_ghp_sync+
     attr_accessor :name
-    
+
     # If you want to use a non-local {doc_dir} (a remote host), set this to +false+.
-    # 
+    #
     # @return [true,false] whether to throw an error if {doc_dir} does not exist; default: +true+
     attr_accessor :strict
-    
+
     # @note You should pass in multi-args separately: +['--exclude','*~']+
     # @note You should not single/double quote the args; +['"*~"']+ is unnecessary.
-    # 
+    #
     # @return [Array<String>] the args to pass to the {sync_cmd}; default: +['-ahv','--progress']+
     attr_accessor :sync_args
-    
+
     # @return [String] the sync command to use on the command line; default: +rsync+
     attr_accessor :sync_cmd
-    
+
     alias_method :strict?,:strict
-    
+
     # @param name [Symbol] the name of this task to use on the command line with +rake+
-    def initialize(name=:yard_ghp_sync)
+    def initialize(name = :yard_ghp_sync)
+      super()
+
       @after = nil
       @arg_names = []
       @before = nil
@@ -121,62 +89,61 @@ module YardGhurt
       @strict = true
       @sync_args = ['-ahv','--progress']
       @sync_cmd = 'rsync'
-      
-      yield self if block_given?()
-      define()
+
+      yield(self) if block_given?
+      define
     end
-    
+
     # Define the Rake task and description using the instance variables.
-    def define()
+    def define
       @arg_names = *@arg_names
       @arg_names.unshift(:deploy) unless @arg_names.include?(:deploy)
-      
+
       desc @description
-      task @name,@arg_names => Array(@deps) do |task,args|
+      task @name,@arg_names => Array(@deps) do |_task,args|
         deploy = Util.to_bool(args.deploy)
-        
+
         @before.call(self,args) if @before.respond_to?(:call)
-        
-        # Without these checks, sh raises some pretty cryptic errors.
-        if @strict
-          # If you want to use a non-local dir, set strict to false.
-          if !File.exist?(@doc_dir)
-            raise ArgumentError,%Q(#{self.class}.doc_dir [#{@doc_dir}] does not exist; execute "rake yard"?)
-          end
+
+        # Without the below checks, sh() raises some pretty cryptic errors.
+
+        # If you want to use a non-local dir, set strict to false.
+        if @strict && !File.exist?(@doc_dir)
+          raise ArgumentError,%(#{self.class}.doc_dir [#{@doc_dir}] does not exist; execute "rake yard"?)
         end
         # Do not check if ghp_dir exists because rsync may create it.
-        if @ghp_dir.nil?() || @ghp_dir.to_s().strip().empty?()
+        if @ghp_dir.nil? || @ghp_dir.to_s.strip.empty?
           raise ArgumentError,"#{self.class}.ghp_dir must be set"
         end
-        
+
         sh(*build_sh_cmd(deploy))
-        
+
         if !deploy
           puts
-          puts %Q(Execute "rake #{@name}[true]" for actually deploying (not a dry-run))
+          puts %(Execute "rake #{@name}[true]" for actually deploying (not a dry-run))
         end
-        
+
         @after.call(self,args) if @after.respond_to?(:call)
       end
-      
+
       return self
     end
-    
+
     # Build the sync command to use on the command line.
-    # 
+    #
     # @param deploy [true,false] whether to actually deploy (+true+) or to run a dry-run (+false+)
-    # 
+    #
     # @return [Array<String>] the sync command and its args
     def build_sh_cmd(deploy)
       sh_cmd = [@sync_cmd]
-      
+
       sh_cmd << '--dry-run' unless deploy
       sh_cmd.push(*@sync_args)
-      
+
       # File.join() to add a trailing '/' if not present
       sh_cmd << File.join(@doc_dir,'')
       sh_cmd << File.join(@ghp_dir,'')
-      
+
       return sh_cmd
     end
   end

data/lib/yard_ghurt/util.rb

@@ -1,81 +1,123 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019 Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 module YardGhurt
-  ###
   # Utility methods in a separate module/mixin,
   # so that a programmer can require/load a sole task:
   #   require 'yard_ghurt/gfm_fix_task'
-  # 
+  #
   # Else, programmers would be required to always require/load the entire +yard_ghurt+ module:
   #   require 'yard_ghurt'
-  # 
+  #
   # All internal code should use this module.
-  # 
+  #
   # External code can either use this module or {YardGhurt},
   # which includes this module as a mixin.
-  # 
-  # @author Jonathan Bradley Whited (@esotericpig)
-  # @since  1.0.0
-  ###
+  #
+  # @since 1.0.0
   module Util
     # @return [Array<String>] the lower-case Strings that will equal to +true+
-    TRUE_BOOLS = ['1','on','t','true','y','yes'].freeze()
-    
+    TRUE_BOOLS = %w[1 on t true y yes].freeze
+
+    # @return a very flexible (non-strict) Semantic Versioning regex, ignoring pre-release/build-metadata
+    # @since 1.2.1
+    SEM_VER_REGEX = /(?<major>\d+)(?:\.(?<minor>\d+))?(?:\.(?<patch>\d+))?/.freeze
+
     # If +include Util+ is called, extend {ClassMethods}.
-    # 
+    #
     # @param mod [Module] the module to extend
     def self.included(mod)
       mod.extend ClassMethods
     end
-    
+
     module ClassMethods
+      @yard_sem_ver = nil
+
       # If +filename+ exists, delete it, and if +output+ is +true+, log it to stdout.
-      # 
+      #
       # @param filename [String] the file to remove
       # @param output [true,false] whether to log it to stdout
-      def rm_exist(filename,output=true)
+      def rm_exist(filename,output = true)
         return unless File.exist?(filename)
-        
+
         puts "[#{filename}]: - Deleted" if output
         File.delete(filename)
       end
-      
+
       # Convert +str+ to +true+ or +false+.
-      # 
+      #
       # Even if +str+ is not a String, +to_s()+ will be called, so should be safe.
-      # 
+      #
       # @param str [String,Object] the String (or Object) to convert
-      # 
+      #
       # @return [true,false] the boolean value of +str+
-      # 
+      #
       # @see TRUE_BOOLS
       # @see GHPSyncTask#arg_names
       def to_bool(str)
-        return TRUE_BOOLS.include?(str.to_s().downcase())
+        return TRUE_BOOLS.include?(str.to_s.downcase)
+      end
+
+      # Parse +str+ as a non-strict Semantic Version:
+      #   \d+.\d+.\d+
+      #
+      # Unlike the specification, minor and patch are optional.
+      # Also, pre-release and build metadata are ignored.
+      # This is used for checking the YARD version internally,
+      # so needs to be very flexible.
+      #
+      # @param str [String,Object] the object to parse; +to_s()+ will be called on it
+      # @return [Hash] the Semantic Version parts: +{:major, :minor, :patch}+
+      #                defaults all values to +0+ if the version cannot be parsed
+      # @see SEM_VER_REGEX
+      # @see #yard_sem_ver
+      # @since 1.2.1
+      def parse_sem_ver(str)
+        sem_ver = {
+          major: 0,minor: 0,patch: 0,
+        }
+
+        match = SEM_VER_REGEX.match(str.to_s.gsub(/\s+/u,''))
+
+        return sem_ver unless match
+
+        sem_ver[:major] = match[:major].to_i
+        sem_ver[:minor] = match[:minor].to_i unless match[:minor].nil?
+        sem_ver[:patch] = match[:patch].to_i unless match[:patch].nil?
+
+        return sem_ver
+      end
+
+      # Returns YARD's version as a +Hash+ of parts:
+      #   { major: 0, minor: 0, patch: 0 }
+      #
+      # If the version can not be parsed, it will return the exact
+      # same +Hash+ as above with all values to +0+.
+      #
+      # On initial call, it will parse it and store it.
+      # On subsequent calls, it will return the stored value.
+      #
+      # @return [Hash] YARD's version parts
+      # @see parse_sem_ver
+      # @since 1.2.1
+      def yard_sem_ver
+        return @yard_sem_ver unless @yard_sem_ver.nil?
+
+        require 'yard'
+
+        @yard_sem_ver = parse_sem_ver(defined?(YARD::VERSION) ? YARD::VERSION : '')
+
+        return @yard_sem_ver
       end
     end
-    
+
     extend ClassMethods
   end
 end

data/lib/yard_ghurt/version.rb

@@ -1,26 +1,13 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019 Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 module YardGhurt
-  VERSION = '1.2.0'
+  VERSION = '1.2.2'
 end

data/lib/yard_ghurt.rb

@@ -1,26 +1,13 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2020 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019 Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 require 'optparse'
 require 'yard_ghurt/anchor_links'
 require 'yard_ghurt/gfm_fix_task'
@@ -28,73 +15,66 @@ require 'yard_ghurt/ghp_sync_task'
 require 'yard_ghurt/util'
 require 'yard_ghurt/version'
 
-
-###
 # YARDoc GitHub Rake Tasks
-# 
-# @author Jonathan Bradley Whited (@esotericpig)
-# @since  1.0.0
-###
+#
+# @since 1.0.0
 module YardGhurt
   # Internal code should use +Util.+!
   # See {Util} for details.
   include Util
-  
-  ###
+
   # A simple CLI app used in file +bin/yard_ghurt+.
-  # 
+  #
   # Mainly for getting GitHub/YARDoc anchor link IDs.
-  # 
-  # @author Jonathan Bradley Whited (@esotericpig)
-  # @since  1.2.0
-  ###
+  #
+  # @since 1.2.0
   class App
     attr_reader :args
-    
-    def initialize(args=ARGV)
+
+    def initialize(args = ARGV)
       super()
-      
+
       @args = args
     end
-    
-    def run()
-      parser = OptionParser.new() do |op|
+
+    def run
+      parser = OptionParser.new do |op|
         op.program_name = 'yard_ghurt'
         op.version = VERSION
-        
+
         op.banner = "Usage: #{op.program_name} [options]"
-        
+
         op.on('-a','--anchor <string>','Print GitHub & YARDoc anchor link IDs of <string>') do |str|
-          al = AnchorLinks.new()
+          al = AnchorLinks.new
           puts "GitHub: #{al.to_github_anchor_id(str)}"
           puts "YARDoc: #{al.to_yard_anchor_id(str)}"
           exit
         end
         op.on('-g','--github <string>','Print GitHub anchor link ID of <string>') do |str|
-          al = AnchorLinks.new()
+          al = AnchorLinks.new
           puts al.to_github_anchor_id(str)
           exit
         end
         op.on('-y','--yard <string>','Print YARDoc anchor link ID of <string>') do |str|
-          al = AnchorLinks.new()
+          al = AnchorLinks.new
           puts al.to_yard_anchor_id(str)
           exit
         end
-        
-        op.separator op.summary_indent + '---'
-        
-        op.on_tail('-h','--help','Print this help') do
+
+        op.separator("#{op.summary_indent}---")
+
+        op.on_tail('-h','--help','Show help') do
           puts op
           exit
         end
-        op.on_tail('-v','--version','Print the version') do
+        op.on_tail('-v','--version','Show version') do
           puts "#{op.program_name} v#{op.version}"
           exit
         end
       end
-      
+
       parser.parse!(@args)
-      puts parser # Print help if nothing was parsed
+      puts parser # Print help if nothing was parsed.
     end
   end
 end

data/yard_ghurt.gemspec

@@ -3,62 +3,58 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2020 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019 Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
+require_relative 'lib/yard_ghurt/version'
 
-lib = File.expand_path(File.join('..','lib'),__FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-
-require 'yard_ghurt/version'
-
-Gem::Specification.new() do |spec|
+Gem::Specification.new do |spec|
   spec.name        = 'yard_ghurt'
   spec.version     = YardGhurt::VERSION
-  spec.authors     = ['Jonathan Bradley Whited (@esotericpig)']
-  spec.email       = ['bradley@esotericpig.com']
+  spec.authors     = ['Bradley Whited']
+  spec.email       = ['code@esotericpig.com']
   spec.licenses    = ['LGPL-3.0-or-later']
   spec.homepage    = 'https://github.com/esotericpig/yard_ghurt'
-  spec.summary     = 'YARDoc GitHub Rake Tasks'
-  spec.description = "#{spec.summary}. Fix GitHub Flavored Markdown (GFM) files."
-  
+  spec.summary     = 'YARDoc GitHub Rake Tasks.'
+  spec.description = "#{spec.summary} Fix GitHub Flavored Markdown (GFM) files."
+
   spec.metadata = {
-    'bug_tracker_uri'   => 'https://github.com/esotericpig/yard_ghurt/issues',
-    'changelog_uri'     => 'https://github.com/esotericpig/yard_ghurt/blob/master/CHANGELOG.md',
-    'documentation_uri' => 'https://esotericpig.github.io/docs/yard_ghurt/yardoc/index.html',
-    'homepage_uri'      => 'https://github.com/esotericpig/yard_ghurt',
-    'source_code_uri'   => 'https://github.com/esotericpig/yard_ghurt'
+    'rubygems_mfa_required' => 'true',
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => 'https://github.com/esotericpig/yard_ghurt',
+    'documentation_uri'     => 'https://esotericpig.github.io/docs/yard_ghurt/yardoc/index.html',
+    'bug_tracker_uri'       => 'https://github.com/esotericpig/yard_ghurt/issues',
   }
-  
-  spec.require_paths = ['lib']
-  spec.bindir        = 'bin'
-  spec.executables   = [spec.name]
-  
-  spec.files = Dir.glob(File.join("{#{spec.require_paths.join(',')}}",'**','*.{erb,rb}')) +
-               Dir.glob(File.join(spec.bindir,'**',"{#{spec.executables.join(',')}}")) +
-               Dir.glob(File.join('{test,yard}','**','*.{erb,rb}')) +
-               %W( Gemfile #{spec.name}.gemspec Rakefile ) +
-               %w( CHANGELOG.md LICENSE.txt README.md )
-  
-  spec.required_ruby_version = '>= 2.1.10'
-  
-  spec.add_runtime_dependency 'rake' #,'~> 12.3'
-  
-  spec.add_development_dependency 'bundler'  ,'~> 1.17'
-  spec.add_development_dependency 'rdoc'     ,'~> 6.1'  # For RDoc for YARD (*.rb)
-  spec.add_development_dependency 'redcarpet','~> 3.5'  # For Markdown for YARD (*.md)
-  spec.add_development_dependency 'yard'     ,'~> 0.9'
+
+  spec.required_ruby_version = '>= 2.3'
+  spec.require_paths         = ['lib']
+  spec.bindir                = 'bin'
+  spec.executables           = [spec.name]
+
+  spec.files = [
+    Dir.glob("{#{spec.require_paths.join(',')}}/**/*.{erb,rb}"),
+    Dir.glob("#{spec.bindir}/*"),
+    Dir.glob('{spec,test,yard}/**/*.{erb,rb}'),
+    %W[Gemfile #{spec.name}.gemspec Rakefile .yardopts],
+    %w[LICENSE.txt README.md],
+  ].flatten
+
+  # TEST: Test using different Gem versions:
+  #         GST=1 bundle update && bundle exec rake doc
+  gemspec_test = ENV.fetch('GST','').to_s.strip
+  yard_gemv = false
+
+  if !gemspec_test.empty?
+    case gemspec_test
+    when '1' then yard_gemv = '0.9.24'
+    end
+
+    puts 'Using Gem versions:'
+    puts "  yard: #{yard_gemv.inspect}"
+  end
+
+  spec.add_dependency 'rake'                     # 13.0.3.
+  spec.add_dependency 'yard',yard_gemv || '>= 0' # 0.9.26, 0.9.24 (diff).
 end