yard_ghurt 1.0.0

data/lib/yard_ghurt/ghp_syncer_task.rb

@@ -0,0 +1,183 @@
+#!/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/>.
+#++
+
+
+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::GHPSyncerTask.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::GHPSyncerTask.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.0.0
+  ###
+  class GHPSyncerTask < 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)
+      @after = nil
+      @arg_names = []
+      @before = nil
+      @deps = []
+      @description = 'Sync YARDoc to GitHub Pages repo'
+      @doc_dir = 'doc'
+      @ghp_dir = nil
+      @name = name
+      @strict = true
+      @sync_args = ['-ahv','--progress']
+      @sync_cmd = 'rsync'
+      
+      yield self if block_given?()
+      define()
+    end
+    
+    # Define the Rake task and description using the instance variables.
+    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|
+        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
+        end
+        # Do not check if ghp_dir exists because rsync may create it.
+        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))
+        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
+end

data/lib/yard_ghurt/util.rb

@@ -0,0 +1,80 @@
+#!/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/>.
+#++
+
+
+module YardGhurt
+  ###
+  # Utility methods in a separate module/mixin,
+  # so that a programmer can require/load a sole task:
+  #   require 'yard_ghurt/gfm_fixer_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.
+  # 
+  # All external code should use {YardGhurt}, which includes this module as a mixin.
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @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()
+    
+    # If +include Util+ is called, extend {ClassMethods}.
+    # 
+    # @param mod [Module] the module to extend
+    def self.included(mod)
+      mod.extend ClassMethods
+    end
+    
+    module ClassMethods
+      # 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)
+        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 GHPSyncerTask#arg_names
+      def to_bool(str)
+        return TRUE_BOOLS.include?(str.to_s().downcase())
+      end
+    end
+    
+    extend ClassMethods
+  end
+end

data/lib/yard_ghurt/version.rb

@@ -0,0 +1,26 @@
+#!/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/>.
+#++
+
+
+module YardGhurt
+  VERSION = '1.0.0'
+end

data/lib/yard_ghurt.rb

@@ -0,0 +1,41 @@
+#!/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/>.
+#++
+
+
+require 'yard_ghurt/anchor_links'
+require 'yard_ghurt/gfm_fixer_task'
+require 'yard_ghurt/ghp_syncer_task'
+require 'yard_ghurt/util'
+require 'yard_ghurt/version'
+
+###
+# YARDoc GitHub Rake Tasks
+# 
+# @author Jonathan Bradley Whited (@esotericpig)
+# @since  1.0.0
+###
+module YardGhurt
+  # Internal code should use +Util.+!
+  # External code should use +YardGhurt.+, but can also use +YardGhurt::Util.+.
+  # See {Util} for details.
+  include Util
+end

data/yard/templates/default/layout/html/footer.erb

@@ -0,0 +1,5 @@
+<%# To reduce number of diffs, removed: time, YARD version, and Ruby version. %>
+<div id="footer">
+  Generated by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>.
+</div>

data/yard_ghurt.gemspec

@@ -0,0 +1,60 @@
+# 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/>.
+#++
+
+
+lib = File.expand_path('../lib',__FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'yard_ghurt/version'
+
+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.licenses    = ['LGPL-3.0-or-later']
+  spec.homepage    = 'https://github.com/esotericpig/yard_ghurt'
+  spec.summary     = 'YARDoc GitHub Rake Tasks'
+  spec.description = 'YARDoc GitHub Rake Tasks. 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'
+  }
+  
+  spec.require_paths = ['lib']
+  
+  spec.files = Dir.glob(File.join("{#{spec.require_paths.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.4'  # For Markdown for YARD (*.md)
+  spec.add_development_dependency 'yard'     ,'~> 0.9'
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: yard_ghurt
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonathan Bradley Whited (@esotericpig)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: YARDoc GitHub Rake Tasks. Fix GitHub Flavored Markdown (GFM) files.
+email:
+- bradley@esotericpig.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/yard_ghurt.rb
+- lib/yard_ghurt/anchor_links.rb
+- lib/yard_ghurt/gfm_fixer_task.rb
+- lib/yard_ghurt/ghp_syncer_task.rb
+- lib/yard_ghurt/util.rb
+- lib/yard_ghurt/version.rb
+- yard/templates/default/layout/html/footer.erb
+- yard_ghurt.gemspec
+homepage: https://github.com/esotericpig/yard_ghurt
+licenses:
+- LGPL-3.0-or-later
+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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.10
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.4
+signing_key: 
+specification_version: 4
+summary: YARDoc GitHub Rake Tasks
+test_files: []