sleeping_king_studios-docs 0.2.0 → 0.3.0

data/lib/sleeping_king_studios/docs/commands/installation/install_jekyll.rb

@@ -1,273 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-
-require 'erubi'
-
-require 'sleeping_king_studios/docs/commands/installation'
-require 'sleeping_king_studios/docs/commands/installation/install_templates'
-
-module SleepingKingStudios::Docs::Commands::Installation
-  # Installs the Jekyll application.
-  class InstallJekyll < Cuprum::Command # rubocop:disable Metrics/ClassLength
-    # @overload initialize(**options)
-    #   @param options [Hash] additional options for the command.
-    #
-    #   @option options description [String] a short description of the
-    #     documented library.
-    #   @option options dry_run [Boolean] if true, does not apply filesystem
-    #     changes. Defaults to false.
-    #   @option options name [String] the name of the documented library.
-    #   @option options repository [String] the URL of the library repository.
-    #   @option options verbose [Boolean] if true, prints updates to STDOUT.
-    #     Defaults to true.
-    def initialize(error_stream: $stderr, output_stream: $stdout, **options)
-      super()
-
-      @error_stream  = error_stream
-      @output_stream = output_stream
-      @options       = options
-    end
-
-    # @return [String] a short description of the documented library.
-    def description
-      @options.fetch(:description, 'A Ruby library.')
-    end
-
-    # @return [Boolean] if true, does not apply filesystem changes.
-    def dry_run?
-      @options.fetch(:dry_run, false)
-    end
-
-    # @return [String] the name of the documented library.
-    def name
-      @options.fetch(:name, 'Library Name')
-    end
-
-    # @return [String] the URL of the library repository.
-    def repository
-      @options.fetch(:repository, 'www.example.com')
-    end
-
-    # @return [Boolean] if true, prints updates to STDOUT.
-    def verbose?
-      @options.fetch(:verbose, true)
-    end
-
-    private
-
-    attr_reader :docs_path
-
-    attr_reader :error_stream
-
-    attr_reader :output_stream
-
-    attr_reader :project_path
-
-    def create_configuration
-      file_path = File.join(docs_path, '_config.yml')
-
-      return if File.exist?(file_path)
-
-      output '  - Generating Jekyll configuration'
-
-      return if dry_run?
-
-      File.write(
-        file_path,
-        evaluate_template(File.join(templates_path, 'config.yml.erb'))
-      )
-    end
-
-    def create_directory
-      return if Dir.exist?(docs_path)
-
-      output "  - Creating Jekyll directory at #{docs_path}"
-
-      return if dry_run?
-
-      FileUtils.mkdir_p docs_path
-    end
-
-    def create_index_page
-      file_path = File.join(docs_path, 'index.md')
-
-      return if File.exist?(file_path)
-
-      output '  - Generating index page'
-
-      return if dry_run?
-
-      File.write(
-        file_path,
-        evaluate_template(File.join(templates_path, 'pages', 'index.md.erb'))
-      )
-    end
-
-    def create_pages
-      step { create_index_page }
-      step { create_reference_page }
-      step { create_versions_page }
-    end
-
-    def create_reference_page # rubocop:disable Metrics/MethodLength
-      dir_path = File.join(docs_path, 'reference')
-
-      FileUtils.mkdir_p(dir_path) unless dry_run?
-
-      file_path = File.join(dir_path, 'index.md')
-
-      return if File.exist?(file_path)
-
-      output '  - Generating reference page'
-
-      return if dry_run?
-
-      File.write(
-        file_path,
-        evaluate_template(
-          File.join(templates_path, 'pages', 'reference.md.erb')
-        )
-      )
-    end
-
-    def create_versions_page # rubocop:disable Metrics/MethodLength
-      dir_path = File.join(docs_path, 'versions')
-
-      FileUtils.mkdir_p(dir_path) unless dry_run?
-
-      file_path = File.join(dir_path, 'index.md')
-
-      return if File.exist?(file_path)
-
-      output '  - Generating versions page'
-
-      return if dry_run?
-
-      File.write(
-        file_path,
-        evaluate_template(
-          File.join(templates_path, 'pages', 'versions.md.erb')
-        )
-      )
-    end
-
-    def evaluate_template(template_path)
-      template = File.read(template_path)
-      engine   = Erubi::Engine.new(template).src
-
-      eval(engine, local_binding) # rubocop:disable Security/Eval
-    end
-
-    def install_templates
-      includes_path = File.join(docs_path, '_includes')
-
-      FileUtils.mkdir_p(includes_path) unless dry_run?
-
-      output '  - Installing Jekyll templates'
-
-      file_path = File.join(includes_path, 'breadcrumbs.md')
-
-      unless File.exist?(file_path)
-        template_path = File.join(templates_path, 'includes', 'breadcrumbs.md')
-
-        File.write(file_path, File.read(template_path)) unless dry_run?
-      end
-
-      install_reference_templates
-    end
-
-    def install_reference_templates
-      SleepingKingStudios::Docs::Commands::Installation::InstallTemplates
-        .new(
-          dry_run:         dry_run?,
-          force:           false,
-          ignore_existing: true,
-          verbose:         false
-        )
-        .call(docs_path:)
-    end
-
-    def jekyll_cache_path
-      File.join(docs_path, '.jekyll-cache').sub(/\A\./, '')
-    end
-
-    def jekyll_site_path
-      File.join(docs_path, '_site').sub(/\A\./, '')
-    end
-
-    def local_binding
-      return @local_binding if @local_binding
-
-      description = self.description
-      name        = self.name
-      repository  = self.repository
-
-      @local_binding = binding
-    end
-
-    def output(string)
-      return unless verbose?
-
-      output_stream.puts(string)
-    end
-
-    def process(docs_path:, project_path: Dir.pwd)
-      @docs_path    = docs_path
-      @project_path = project_path
-
-      output "Installing SleepingKingStudios::YARD to #{docs_path}..."
-
-      step { update_gitignore }
-      step { create_directory }
-      step { create_configuration }
-      step { create_pages }
-      step { install_templates }
-
-      output 'Done!'
-    end
-
-    def templates_path
-      @templates_path ||=
-        File.join(
-          SleepingKingStudios::Docs.gem_path,
-          'lib',
-          'sleeping_king_studios',
-          'docs',
-          'templates'
-        )
-    end
-
-    def update_gitignore
-      file_path = File.join(project_path, '.gitignore')
-
-      FileUtils.touch(file_path) unless dry_run?
-
-      original_contents = File.read(file_path)
-      updated_contents  = update_gitignore_contents(original_contents:)
-
-      return if updated_contents == original_contents
-
-      output '  - Updating .gitignore'
-
-      File.write(file_path, updated_contents) unless dry_run?
-    end
-
-    def update_gitignore_contents(original_contents:) # rubocop:disable Metrics/MethodLength
-      updated = original_contents
-      ignored = original_contents.each_line.map(&:strip)
-
-      unless ignored.include?(jekyll_cache_path)
-        updated += "\n" unless updated.empty? || updated.end_with?("\n")
-        updated += "#{jekyll_cache_path}\n"
-      end
-
-      unless ignored.include?(jekyll_site_path)
-        updated += "\n" unless updated.end_with?("\n")
-        updated += "#{jekyll_site_path}\n"
-      end
-
-      updated
-    end
-  end
-end

data/lib/sleeping_king_studios/docs/commands/installation/install_templates.rb

@@ -1,125 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-
-require 'sleeping_king_studios/docs/commands/installation'
-require 'sleeping_king_studios/docs/errors/file_already_exists'
-
-module SleepingKingStudios::Docs::Commands::Installation
-  # Installs the Liquid template files.
-  class InstallTemplates < Cuprum::Command
-    # @overload initialize(**options)
-    #   @param options [Hash] additional options for the command.
-    #
-    #   @option options dry_run [Boolean] if true, does not apply filesystem
-    #     changes. Defaults to false.
-    #   @option options force [Boolean] if true, replaces existing template
-    #     files.
-    #   @option options ignore_existing [Boolean] if true, does not attempt to
-    #     copy over existing files.
-    #   @option options verbose [Boolean] if true, prints updates to STDOUT.
-    #     Defaults to true.
-    def initialize(error_stream: $stderr, output_stream: $stdout, **options)
-      super()
-
-      @error_stream  = error_stream
-      @output_stream = output_stream
-      @options       = options
-    end
-
-    # @return [Boolean] if true, does not apply filesystem changes.
-    def dry_run?
-      @options.fetch(:dry_run, false)
-    end
-
-    # @return [Boolean] if true, overwrites existing template files.
-    def force?
-      @options.fetch(:force, false)
-    end
-
-    # @return [Boolean] if true, does not attempt to copy over existing files.
-    def ignore_existing?
-      @options.fetch(:ignore_existing, false)
-    end
-
-    # @return [Boolean] if true, prints updates to STDOUT.
-    def verbose?
-      @options.fetch(:verbose, true)
-    end
-
-    private
-
-    attr_reader :docs_path
-
-    attr_reader :error_stream
-
-    attr_reader :output_stream
-
-    def check_for_existing_file(filename)
-      return if force?
-      return unless File.exist?(filename)
-
-      error =
-        SleepingKingStudios::Docs::Errors::FileAlreadyExists
-        .new(path: filename)
-
-      error_stream.puts("Error: #{error.message}")
-
-      failure(error)
-    end
-
-    def copy_template(template_path)
-      install_path  = File.join(docs_path, '_includes', 'reference')
-      relative_path = template_path.sub("#{templates_path}/", '')
-      absolute_path = File.join(install_path, relative_path)
-
-      return if ignore_existing? && File.exist?(absolute_path)
-
-      output "  - Copying template #{relative_path}"
-
-      step { check_for_existing_file(absolute_path) }
-
-      FileUtils.mkdir_p(File.dirname(absolute_path)) unless dry_run?
-      FileUtils.copy(template_path, absolute_path) unless dry_run?
-    end
-
-    def each_template(&)
-      return enum_for(:each_template) unless block_given?
-
-      Dir[templates_pattern].each(&)
-    end
-
-    def output(string)
-      return unless verbose?
-
-      output_stream.puts(string)
-    end
-
-    def process(docs_path:)
-      @docs_path = docs_path
-
-      output "Copying template files (force=#{force?})..."
-
-      each_template { |template_path| step { copy_template(template_path) } }
-
-      output 'Done!'
-    end
-
-    def templates_path
-      @templates_path ||=
-        File.join(
-          SleepingKingStudios::Docs.gem_path,
-          'lib',
-          'sleeping_king_studios',
-          'docs',
-          'templates',
-          'includes',
-          'reference'
-        )
-    end
-
-    def templates_pattern
-      @templates_pattern ||= File.join(templates_path, '**', '*.md')
-    end
-  end
-end

data/lib/sleeping_king_studios/docs/commands/installation/install_workflow.rb

@@ -1,121 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-
-require 'erubi'
-
-require 'sleeping_king_studios/docs/commands/installation'
-require 'sleeping_king_studios/docs/errors/file_already_exists'
-
-module SleepingKingStudios::Docs::Commands::Installation
-  # Installs the GitHub pages CI workflow.
-  class InstallWorkflow < Cuprum::Command
-    # @overload initialize(**options)
-    #   @param options [Hash] additional options for the command.
-    #
-    #   @option options dry_run [Boolean] if true, does not apply filesystem
-    #     changes. Defaults to false.
-    #   @option options force [Boolean] if true, replaces existing template
-    #     files.
-    #   @option options verbose [Boolean] if true, prints updates to STDOUT.
-    #     Defaults to true.
-    def initialize(error_stream: $stderr, output_stream: $stdout, **options)
-      super()
-
-      @error_stream  = error_stream
-      @output_stream = output_stream
-      @options       = options
-    end
-
-    # @return [Boolean] if true, does not apply filesystem changes.
-    def dry_run?
-      @options.fetch(:dry_run, false)
-    end
-
-    # @return [Boolean] if true, overwrites existing template files.
-    def force?
-      @options.fetch(:force, false)
-    end
-
-    # @return [Boolean] if true, prints updates to STDOUT.
-    def verbose?
-      @options.fetch(:verbose, true)
-    end
-
-    private
-
-    attr_reader :error_stream
-
-    attr_reader :output_stream
-
-    def check_for_existing_file(filename)
-      return if force?
-      return unless File.exist?(filename)
-
-      error =
-        SleepingKingStudios::Docs::Errors::FileAlreadyExists
-        .new(path: filename)
-
-      error_stream.puts("Error: #{error.message}")
-
-      failure(error)
-    end
-
-    def create_workflow(workflow_path)
-      file_path = File.join(workflow_path, 'deploy-pages.yml')
-
-      step { check_for_existing_file(file_path) }
-
-      return if dry_run?
-
-      File.write(
-        file_path,
-        evaluate_template(File.join(templates_path, 'deploy-pages.yml.erb'))
-      )
-    end
-
-    def evaluate_template(template_path)
-      template = File.read(template_path)
-      engine   = Erubi::Engine.new(template).src
-
-      eval(engine, local_binding) # rubocop:disable Security/Eval
-    end
-
-    def local_binding
-      return @local_binding if @local_binding
-
-      ruby_version = RUBY_VERSION.split('.')[0..1].join('.')
-
-      @local_binding = binding
-    end
-
-    def output(string)
-      return unless verbose?
-
-      output_stream.puts(string)
-    end
-
-    def process(root_path: Dir.pwd)
-      workflow_path = File.join(root_path, '.github', 'workflows')
-
-      output 'Adding GitHub pages workflow...'
-
-      FileUtils.mkdir_p(workflow_path) unless dry_run?
-
-      step { create_workflow(workflow_path) }
-
-      output 'Done!'
-    end
-
-    def templates_path
-      @templates_path ||=
-        File.join(
-          SleepingKingStudios::Docs.gem_path,
-          'lib',
-          'sleeping_king_studios',
-          'docs',
-          'templates'
-        )
-    end
-  end
-end

data/lib/sleeping_king_studios/docs/commands/installation.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-require 'sleeping_king_studios/docs/commands'
-
-module SleepingKingStudios::Docs::Commands
-  # Namespace for installation commands, which set up an application with docs.
-  module Installation
-    autoload :InstallJekyll,
-      'sleeping_king_studios/docs/commands/installation/install_jekyll'
-    autoload :InstallTemplates,
-      'sleeping_king_studios/docs/commands/installation/install_templates'
-    autoload :InstallWorkflow,
-      'sleeping_king_studios/docs/commands/installation/install_workflow'
-  end
-end

data/lib/sleeping_king_studios/docs/commands/write_file.rb

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-
-require 'cuprum/command'
-require 'cuprum/exception_handling'
-
-require 'sleeping_king_studios/docs/commands'
-
-module SleepingKingStudios::Docs::Commands
-  # Writes the given contents to a file.
-  class WriteFile < Cuprum::Command
-    include Cuprum::ExceptionHandling
-
-    # @!method call(contents:, file_path:)
-    #   Writes the given contents to the specified file.
-    #
-    #   Recursively generates the required directories, if needed.
-    #
-    #   @param contents [String] the contents to write.
-    #   @param file_path [String] the path of the file.
-    #
-    #   @return [Cuprum::Result] a passing result if the directories are
-    #     successfully created and the file is successfully written.
-    #   @return [Cuprum::Result<Cuprum::Error>] a failing result if the command
-    #     was unable to create the directories or write the file.
-
-    # @param force [Boolean] if true, overwrites an existing file.
-    def initialize(force: false)
-      super()
-
-      @force = force
-    end
-
-    # @return [Boolean] if true, overwrites an existing file.
-    def force?
-      @force
-    end
-
-    private
-
-    def check_if_file_exists(file_path:)
-      return if     force?
-      return unless File.exist?(file_path)
-
-      error =
-        SleepingKingStudios::Docs::Errors::FileAlreadyExists
-        .new(path: file_path)
-
-      failure(error)
-    end
-
-    def create_directory(file_path:)
-      dir_path = File.dirname(file_path)
-
-      FileUtils.mkdir_p(dir_path)
-    rescue Errno::EEXIST => exception
-      failure(invalid_directory_error(exception))
-    end
-
-    def create_file(contents:, file_path:)
-      File.write(file_path, contents)
-    rescue Errno::EISDIR => exception
-      failure(invalid_file_error(exception))
-    end
-
-    def invalid_directory_error(exception)
-      dir_path = exception.message.split(' - ').last
-
-      SleepingKingStudios::Docs::Errors::InvalidDirectory.new(path: dir_path)
-    end
-
-    def invalid_file_error(exception)
-      file_path = exception.message.split(' - ').last
-
-      SleepingKingStudios::Docs::Errors::InvalidFile.new(path: file_path)
-    end
-
-    def process(contents:, file_path:)
-      file_path = File.expand_path(file_path)
-
-      step { check_if_file_exists(file_path:) }
-
-      step { create_directory(file_path:) }
-
-      step { create_file(contents:, file_path:) }
-    end
-  end
-end

data/lib/sleeping_king_studios/docs/commands.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-require 'sleeping_king_studios/docs'
-
-module SleepingKingStudios::Docs
-  # Namespace for commands, which parse and generate documentation files.
-  module Commands
-    autoload :Generate,     'sleeping_king_studios/docs/commands/generate'
-    autoload :Generators,   'sleeping_king_studios/docs/commands/generators'
-    autoload :Installation, 'sleeping_king_studios/docs/commands/installation'
-    autoload :Parse,        'sleeping_king_studios/docs/commands/parse'
-    autoload :WriteFile,    'sleeping_king_studios/docs/commands/write_file'
-  end
-end

data/lib/sleeping_king_studios/docs/registry.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require 'yard'
-
-require 'sleeping_king_studios/docs'
-
-module SleepingKingStudios::Docs
-  # Dependency injection provider wrapping the YARD registry.
-  module Registry
-    # Clears the cached registry, if any.
-    def self.clear
-      @instance = nil
-    end
-
-    # Caches and returns the contents of the YARD registry.
-    #
-    # @return [Array] the cached registry.
-    def self.instance
-      @instance ||= [::YARD::Registry.root, *::YARD::Registry.to_a]
-    end
-  end
-end

data/lib/sleeping_king_studios/docs/tasks/base.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-require 'thor'
-
-require 'sleeping_king_studios/tools/toolbelt'
-
-require 'sleeping_king_studios/docs'
-
-module SleepingKingStudios::Docs
-  module Tasks
-    # Generic base CLI task.
-    class Base < Thor
-      private
-
-      def tools
-        SleepingKingStudios::Tools::Toolbelt.instance
-      end
-    end
-  end
-end