sleeping_king_studios-docs 0.2.1 → 0.3.0

data/lib/sleeping_king_studios/docs/jekyll/commands/generate.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Generates new reference documentation.
+  class Generate < SleepingKingStudios::Docs::Jekyll::Commands::Reference # rubocop:disable Metrics/ClassLength
+    full_name 'docs:jekyll:generate'
+
+    description 'Generates reference documentation for the current version'
+
+    private
+
+    attr_reader :errors
+
+    attr_reader :files
+
+    attr_reader :registry
+
+    def build_command
+      @build_command ||= SleepingKingStudios::Docs::Yard::Build.new
+    end
+
+    def clear_data_directory(path) # rubocop:disable Metrics/MethodLength
+      return unless file_system.directory?(path)
+
+      if dry_run?
+        step { ensure_data_directory_empty(path) }
+
+        return
+      end
+
+      each_data_directory(path) do |child|
+        file_system.delete_directory(child, recursive: true)
+      end
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      error = SleepingKingStudios::Docs::Errors::FileError.new(
+        message: exception.message,
+        path:
+      )
+      failure(error)
+    end
+
+    def clear_directories
+      step { clear_reference_directory }
+
+      step { clear_data_directory(class_data_directory) }
+      step { clear_data_directory(constant_data_directory) }
+      step { clear_data_directory(method_data_directory) }
+      step { clear_data_directory(module_data_directory) }
+      step { clear_data_directory(namespace_data_directory) }
+    end
+
+    def clear_reference_directory # rubocop:disable Metrics/MethodLength
+      return unless file_system.directory?(reference_directory)
+
+      if dry_run?
+        step { ensure_reference_directory_empty }
+
+        return
+      end
+
+      each_reference_directory do |path|
+        file_system.delete_directory(path, recursive: true)
+      end
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      error = SleepingKingStudios::Docs::Errors::FileError.new(
+        message: exception.message,
+        path:    reference_directory
+      )
+      failure(error)
+    end
+
+    def ensure_data_directory_empty(path)
+      matching = each_data_file(path).first
+
+      return unless matching
+
+      path = File.dirname(matching)
+
+      message = "unable to delete directory #{path} - directory is not empty"
+      error   = SleepingKingStudios::Docs::Errors::FileError.new(
+        message:,
+        path:
+      )
+
+      failure(error)
+    end
+
+    def ensure_reference_directory_empty # rubocop:disable Metrics/MethodLength
+      matching = each_reference_file.first
+
+      return unless matching
+
+      path = File.dirname(matching)
+
+      message =
+        "unable to delete directory #{path} - directory is " \
+        'not empty'
+      error   = SleepingKingStudios::Docs::Errors::FileError.new(
+        message:,
+        path:
+      )
+
+      failure(error)
+    end
+
+    def generator_for(object)
+      namespace       = SleepingKingStudios::Docs::Jekyll::Generators
+      generator_class =
+        if object.is_a?(SleepingKingStudios::Docs::Data::ModuleObject)
+          namespace::ReferenceGenerator
+        else
+          namespace::DataGenerator
+        end
+
+      generator_class.new(object:, **generator_options)
+    end
+
+    def generator_options
+      @generator_options ||= {
+        file_system:,
+        standard_io:,
+        docs_path:,
+        dry_run:     dry_run?,
+        quiet:       quiet?,
+        verbose:     verbose?,
+        version:
+      }
+    end
+
+    def handle_generator_result
+      result = yield
+
+      if result.success?
+        files.concat(result.value)
+
+        return
+      end
+
+      errors << result.error
+    end
+
+    def parse_registry
+      @registry = step do
+        SleepingKingStudios::Docs::Yard::Parse.new.call
+      end
+
+      SleepingKingStudios::Docs::Yard::Registry
+        .provider
+        .set(:registry, registry)
+    rescue Plumbum::Errors::ImmutableError => exception
+      message = "#{exception.class}: #{exception.message}"
+      error   = SleepingKingStudios::Docs::Errors::RegistryError.new(message:)
+
+      failure(error)
+    end
+
+    def process # rubocop:disable Metrics/MethodLength
+      @files  = []
+      @errors = []
+
+      step { clear_directories }
+
+      step { parse_registry }
+
+      registry.each do |native|
+        data = step { build_command.call(native) }
+
+        next unless data.public?
+
+        generator = generator_for(data)
+
+        handle_generator_result { generator.call }
+      end
+
+      report_errors
+    end
+
+    def report_errors # rubocop:disable Metrics/MethodLength
+      if errors.empty?
+        say 'Success!'
+
+        return files
+      end
+
+      warn 'Failures:'
+      warn "\n"
+
+      errors.each do |error|
+        warn "  - Unable to generate file #{error.path} - #{error.message}"
+      end
+
+      warn "\n"
+
+      message = 'unable to generate documentation files'
+      error   = Cuprum::Errors::MultipleErrors.new(errors:, message:)
+
+      failure(error)
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/commands/install.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Installs the Jekyll application.
+  class Install < Cuprum::Cli::Command # rubocop:disable Metrics/ClassLength
+    dependency :file_system
+    dependency :standard_io
+
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    TEMPLATES_PATH = SleepingKingStudios::Docs::Jekyll::Commands.templates_path
+    private_constant :TEMPLATES_PATH
+
+    # Generator for writing the Jekyll static pages.
+    class Generator < Cuprum::Cli::Files::Generator
+      output '%<docs_path>s/_config.yml',
+        key:      :config,
+        template: File.join(TEMPLATES_PATH, 'config.yml.erb')
+
+      output '%<docs_path>s/_layouts/page.html',
+        key:      :layout,
+        template: File.join(TEMPLATES_PATH, 'layouts', 'page.html.erb')
+
+      output '%<docs_path>s/index.md',
+        key:      :index,
+        template: File.join(TEMPLATES_PATH, 'pages', 'index.md.erb')
+
+      output '%<docs_path>s/reference/index.md',
+        key:      :reference,
+        template: File.join(TEMPLATES_PATH, 'pages', 'reference.md.erb')
+
+      output '%<docs_path>s/versions/index.md',
+        key:      :versions,
+        template: File.join(TEMPLATES_PATH, 'pages', 'versions.md.erb')
+
+      option :docs_path,           default: 'docs'
+
+      option :project_description, default: ''
+
+      option :project_name,        default: 'Project Name'
+
+      option :project_repository,  default: ''
+    end
+
+    full_name 'docs:jekyll:install'
+
+    description 'Installs the Jekyll application'
+
+    option :docs_path, type: :string,  default: 'docs'
+
+    option :dry_run,   type: :boolean, default: false
+
+    option :gemfile,   type: :boolean, default: true
+
+    option :gitignore, type: :boolean, default: true
+
+    option :templates, type: :boolean, default: true
+
+    option :workflow,  type: :boolean, default: false
+
+    private
+
+    attr_reader :errors
+
+    attr_reader :output_paths
+
+    def create_directory
+      return if file_system.directory?(docs_path)
+
+      say "Generating directory #{docs_path}..."
+      say("\n", verbose: true)
+
+      file_system.create_directory(docs_path, recursive: true) unless dry_run?
+    end
+
+    def create_gemfile
+      gems     = included_gems.map { |k, v| "  gem '#{k}', '#{v}'" }.join("\n")
+      contents = <<~GEMFILE
+        # frozen_string_literal: true
+
+        source 'https://rubygems.org'
+
+        group: :docs do
+        #{gems}
+        end
+      GEMFILE
+
+      say 'Generating Gemfile...'
+      say("\n#{indent(contents, 2)}\n", verbose: true)
+
+      file_system.write_file('Gemfile', contents) unless dry_run?
+    end
+
+    def create_gitignore
+      contents = "# Ignore Jekyll site and temporary files.\n"
+
+      ignored_paths.each { |path| contents = "#{contents}#{path}\n" }
+
+      say 'Generating .gitignore...'
+      say("\n#{indent(contents, 2)}\n", verbose: true)
+
+      file_system.write_file('.gitignore', contents) unless dry_run?
+    end
+
+    def create_static_files # rubocop:disable Metrics/MethodLength
+      static_files = step do
+        Generator
+          .new(
+            file_system:,
+            standard_io:,
+            docs_path:,
+            dry_run:     dry_run?,
+            directories: true,
+            quiet:       quiet?,
+            verbose:     verbose?
+          )
+          .call
+      end
+
+      output_paths.concat(static_files)
+    end
+
+    def handle_file_error(file_path)
+      yield
+
+      success(file_path)
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      warn("  ! #{exception.message}")
+
+      error = Cuprum::Cli::Files::Errors::FileNotWriteable.new(
+        file_path:,
+        message:   exception.message
+      )
+      failure(error)
+    end
+
+    def ignored_paths
+      [
+        "#{docs_path}/_site",
+        "#{docs_path}/.sass-cache",
+        "#{docs_path}/.jekyll-cache",
+        "#{docs_path}/.jekyll-metadata",
+        'vendor'
+      ]
+    end
+
+    def included_gems
+      {
+        'jekyll'              => '~> 4.4',
+        'kramdown-parser-gfm' => '~> 1.1',
+        'webrick'             => '~> 1.8'
+      }
+    end
+
+    def indent(str, count) = tools.string_tools.indent(str, count)
+
+    def install_templates # rubocop:disable Metrics/MethodLength
+      return unless templates?
+
+      template_files = step do
+        SleepingKingStudios::Docs::Jekyll::Commands::InstallTemplates
+          .new(file_system:, standard_io:)
+          .call(
+            docs_path:,
+            dry_run:   dry_run?,
+            quiet:     quiet?,
+            verbose:   verbose?
+          )
+      end
+
+      say("\n", verbose: true)
+
+      output_paths.concat(template_files)
+    end
+
+    def install_workflow # rubocop:disable Metrics/MethodLength
+      return unless workflow?
+
+      workflow_files = step do
+        SleepingKingStudios::Docs::Jekyll::Commands::InstallWorkflow
+          .new(file_system:, standard_io:)
+          .call(
+            dry_run: dry_run?,
+            quiet:   quiet?,
+            verbose: verbose?
+          )
+      end
+
+      output_paths.concat(workflow_files)
+    end
+
+    def merge_gemfile # rubocop:disable Metrics/AbcSize
+      contents = file_system.read_file('Gemfile')
+      existing = contents.each_line.map(&:strip)
+      added    = included_gems.reject { |k, _| existing.include?("gem '#{k}'") }
+
+      return if added.empty?
+
+      gems = added.map { |k, v| "  gem '#{k}', '#{v}'" }.join("\n")
+
+      contents << "\n" unless contents.end_with?("\n\n")
+      contents << "group :docs do\n#{gems}\nend\n"
+
+      say 'Updating Gemfile...'
+      say("\n#{indent(contents, 2)}\n", verbose: true)
+
+      file_system.write_file('Gemfile', contents) unless dry_run?
+    end
+
+    def merge_gitignore # rubocop:disable Metrics/AbcSize
+      contents = file_system.read_file('.gitignore')
+      existing = contents.each_line.map(&:strip)
+      added    = ignored_paths.reject { |path| existing.include?(path) }
+
+      return if added.empty?
+
+      contents << "\n" unless contents.end_with?("\n\n")
+      contents << "# Ignore Jekyll site and temporary files.\n"
+
+      added.each { |path| contents << path << "\n" }
+
+      say 'Updating .gitignore...'
+      say("\n#{indent(contents, 2)}\n", verbose: true)
+
+      file_system.write_file('.gitignore', contents) unless dry_run?
+    end
+
+    def process
+      @output_paths = []
+
+      step { update_gitignore }
+      step { update_gemfile }
+      step { create_directory }
+      step { create_static_files }
+      step { install_templates }
+      step { install_workflow }
+
+      output_paths
+    end
+
+    def update_gemfile
+      return unless gemfile?
+
+      step do
+        handle_file_error('Gemfile') do
+          file_system.file?('Gemfile') ? merge_gemfile : create_gemfile
+        end
+      end
+
+      output_paths << 'Gemfile'
+    end
+
+    def update_gitignore
+      return unless gitignore?
+
+      step do
+        handle_file_error('.gitignore') do
+          file_system.file?('.gitignore') ? merge_gitignore : create_gitignore
+        end
+      end
+
+      output_paths << '.gitignore'
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Command for installing or updating Jekyll templates for docs.
+  class InstallTemplates < Cuprum::Cli::Command
+    dependency :file_system
+    dependency :standard_io
+
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    full_name 'docs:jekyll:install_templates'
+
+    description 'Installs or updates the Jekyll templates'
+
+    option :docs_path,       type: :string,  default: 'docs'
+
+    option :dry_run,         type: :boolean, default: false
+
+    option :force,           type: :boolean, default: false
+
+    option :ignore_existing, type: :boolean, default: false
+
+    private
+
+    def copy_template(template_path)
+      relative_path = template_path[(templates_path.size + 1)...]
+      output_path   = File.join(includes_path, relative_path)
+
+      return success(nil) if ignore_existing? && file_system.file?(output_path)
+
+      handle_file_error(output_path) do
+        write_template_file(output_path:, template_path:) unless dry_run?
+
+        say("  - Copying template #{relative_path}", verbose: true)
+      end
+    end
+
+    def copy_templates # rubocop:disable Metrics/MethodLength
+      output_paths = []
+      errors       = []
+
+      template_files.each do |template_path|
+        result = copy_template(template_path)
+
+        if result.success?
+          output_paths << result.value
+        else
+          errors << result.error
+        end
+      end
+
+      [output_paths, errors]
+    end
+
+    def handle_errors(errors:, output_paths:) # rubocop:disable Metrics/MethodLength
+      return success(output_paths) if errors.empty?
+
+      error =
+        if errors.size == 1
+          errors.first
+        else
+          Cuprum::Errors::MultipleErrors.new(
+            errors:,
+            message: 'unable to copy multiple template files'
+          )
+        end
+
+      build_result(error:, value: output_paths)
+    end
+
+    def handle_file_error(file_path)
+      yield
+
+      success(file_path)
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      warn("  ! #{exception.message}")
+
+      error = Cuprum::Cli::Files::Errors::FileNotWriteable.new(
+        file_path:,
+        message:   exception.message
+      )
+      failure(error)
+    end
+
+    def includes_path
+      @includes_path ||= File.join(docs_path, '_includes')
+    end
+
+    def process
+      say "Copying template files (force=#{force?})..."
+      say("\n", verbose: true)
+
+      output_paths, errors = copy_templates
+
+      handle_errors(errors:, output_paths:)
+    end
+
+    def template_files
+      return @template_files if @template_files
+
+      pattern = "#{templates_path}/**/*.md"
+
+      @template_files = file_system.each_file(pattern).to_a
+    end
+
+    def templates_path
+      File.join(
+        SleepingKingStudios::Docs::Jekyll::Commands.templates_path,
+        'includes'
+      )
+    end
+
+    def write_template_file(output_path:, template_path:)
+      file_system.create_directory(File.dirname(output_path), recursive: true)
+
+      file_system.copy_file(template_path, output_path, force: force?)
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Command for installing a Github workflow to deploy the docs to Pages.
+  class InstallWorkflow < Cuprum::Cli::Command
+    dependency :file_system
+    dependency :standard_io
+
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    # Generator for writing the workflow template.
+    class Generator < Cuprum::Cli::Files::Generator
+      output '%<file_path>s',
+        template: File.join(
+          SleepingKingStudios::Docs::Jekyll::Commands.templates_path,
+          'deploy-pages.yml.erb'
+        )
+
+      option :ruby_version
+    end
+
+    full_name 'docs:jekyll:install_workflow'
+
+    description \
+      'Installs a GitHub workflow to deploy the Jekyll application to Github ' \
+      'Pages'
+
+    option :dry_run, type: :boolean, default: false
+
+    option :file_path,
+      type:    :string,
+      default: '.github/workflows/deploy-pages.yml'
+
+    option :ruby_version,
+      default: -> { RUBY_VERSION.split('.')[..1].join('.') }
+
+    private
+
+    def process
+      Generator
+        .new(
+          file_path,
+          file_system:,
+          standard_io:,
+          **options.except(:file_path)
+        )
+        .call
+    end
+  end
+end