sleeping_king_studios-docs 0.2.0 → 0.3.0

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

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Abstract base class for commands that update the reference documentation.
+  class Reference < 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
+
+    option :docs_path, default: 'docs'
+
+    option :dry_run,   type: :boolean, default: false
+
+    option :version
+
+    # @return [String] the directory for defining class data YAML files.
+    def class_data_directory
+      @class_data_directory ||=
+        if version
+          File.join(docs_path, '_classes', "version--#{version}")
+        else
+          File.join(docs_path, '_classes')
+        end
+    end
+
+    # @return [String] the directory for defining constant data YAML files.
+    def constant_data_directory
+      @constant_data_directory ||=
+        if version
+          File.join(docs_path, '_constants', "version--#{version}")
+        else
+          File.join(docs_path, '_constants')
+        end
+    end
+
+    # @return [String] the directory for defining method data YAML files.
+    def method_data_directory
+      @method_data_directory ||=
+        if version
+          File.join(docs_path, '_methods', "version--#{version}")
+        else
+          File.join(docs_path, '_methods')
+        end
+    end
+
+    # @return [String] the directory for defining module data YAML files.
+    def module_data_directory
+      @module_data_directory ||=
+        if version
+          File.join(docs_path, '_modules', "version--#{version}")
+        else
+          File.join(docs_path, '_modules')
+        end
+    end
+
+    # @return [String] the directory for defining namespace data YAML files.
+    def namespace_data_directory
+      @namespace_data_directory ||=
+        if version
+          File.join(docs_path, '_namespaces', "version--#{version}")
+        else
+          File.join(docs_path, '_namespaces')
+        end
+    end
+
+    # @return [String] the directory for defining reference Markdown files.
+    def reference_directory
+      @reference_directory ||=
+        if version
+          File.join(docs_path, 'versions', version, 'reference')
+        else
+          File.join(docs_path, 'reference')
+        end
+    end
+
+    private
+
+    def delete_directory(path, recursive: false)
+      file_system.delete_directory(path, recursive:) unless dry_run?
+
+      success(path)
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      error = SleepingKingStudios::Docs::Errors::FileError.new(
+        message: exception.message,
+        path:
+      )
+      failure(error)
+    end
+
+    def delete_file(path)
+      file_system.delete_file(path) unless dry_run?
+
+      say("  - Deleting file #{path}", verbose: true)
+
+      success(path)
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      say("  - Unable to delete file #{path}", verbose: true)
+
+      error = SleepingKingStudios::Docs::Errors::FileError.new(
+        message: exception.message,
+        path:
+      )
+      failure(error)
+    end
+
+    def each_data_directory(directory, &)
+      pattern = File.join(directory, '*')
+      enum    =
+        file_system
+        .each_file(pattern)
+        .select { |path| file_system.directory?(path) }
+
+      enum = enum.reject { |file| file.include?('version--') } unless version
+
+      block_given? ? enum.each(&) : enum
+    end
+
+    def each_data_file(directory, &)
+      pattern = File.join(directory, '**/*')
+      enum    =
+        file_system
+        .each_file(pattern)
+        .select { |path| file_system.file?(path) }
+
+      enum = enum.reject { |file| file.include?('version--') } unless version
+
+      block_given? ? enum.each(&) : enum
+    end
+
+    def each_reference_directory(&)
+      pattern = File.join(reference_directory, '*')
+      enum    =
+        file_system
+        .each_file(pattern)
+        .select { |path| file_system.directory?(path) }
+
+      block_given? ? enum.each(&) : enum
+    end
+
+    def each_reference_file(&)
+      pattern = File.join(reference_directory, '**/*')
+      enum    =
+        file_system
+        .each_file(pattern)
+        .select { |path| file_system.file?(path) }
+        .reject { |path| path == File.join(reference_directory, 'index.md') }
+
+      block_given? ? enum.each(&) : enum
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Creates or updates reference documentation.
+  class Update < SleepingKingStudios::Docs::Jekyll::Commands::Reference
+    full_name 'docs:jekyll:update'
+
+    description 'Updates reference documentation for the current version'
+
+    private
+
+    def clobber_files
+      SleepingKingStudios::Docs::Jekyll::Commands::Clobber
+        .new(file_system:, standard_io:)
+        .call(**options)
+    end
+
+    def generate_files
+      SleepingKingStudios::Docs::Jekyll::Commands::Generate
+        .new(file_system:, standard_io:)
+        .call(**options)
+    end
+
+    def process
+      step { clobber_files }
+
+      step { generate_files }
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll'
+
+module SleepingKingStudios::Docs::Jekyll
+  # Namespace for commands which install the Jekyll application.
+  module Commands
+    autoload :BackfillVersions,
+      'sleeping_king_studios/docs/jekyll/commands/backfill_versions'
+    autoload :Clobber,
+      'sleeping_king_studios/docs/jekyll/commands/clobber'
+    autoload :Check,
+      'sleeping_king_studios/docs/jekyll/commands/check'
+    autoload :DocumentVersion,
+      'sleeping_king_studios/docs/jekyll/commands/document_version'
+    autoload :Generate,
+      'sleeping_king_studios/docs/jekyll/commands/generate'
+    autoload :Install,
+      'sleeping_king_studios/docs/jekyll/commands/install'
+    autoload :InstallTemplates,
+      'sleeping_king_studios/docs/jekyll/commands/install_templates'
+    autoload :InstallWorkflow,
+      'sleeping_king_studios/docs/jekyll/commands/install_workflow'
+    autoload :Reference,
+      'sleeping_king_studios/docs/jekyll/commands/reference'
+    autoload :Update,
+      'sleeping_king_studios/docs/jekyll/commands/update'
+
+    # Path to the template files for installing Jekyll.
+    def self.templates_path # rubocop:disable Metrics/MethodLength
+      @templates_path ||=
+        File
+        .join(
+          SleepingKingStudios::Docs.gem_path,
+          'lib',
+          'sleeping_king_studios',
+          'docs',
+          'jekyll',
+          'templates'
+        )
+        .freeze
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/generators/data_generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require 'sleeping_king_studios/docs/jekyll/generators'
+
+module SleepingKingStudios::Docs::Jekyll::Generators
+  # Generator class for writing reference data to the filesystem.
+  class DataGenerator < Cuprum::Cli::Files::Generator
+    DATA_TEMPLATE = Cuprum::Cli::Files::Templates::StringTemplate.new(
+      engine:       Cuprum::Cli::Files::Engines::ERB,
+      raw_template: '<%= data_contents %>'
+    ).freeze
+    private_constant :DATA_TEMPLATE
+
+    option :docs_path,
+      type:    :string,
+      default: 'docs'
+
+    option :object,
+      type:     SleepingKingStudios::Docs::Data::Base,
+      required: true
+
+    option :version, type: :string
+
+    output '%<collection_path>s/%<object_path>s.yml',
+      key:      :data,
+      template: DATA_TEMPLATE
+
+    # @return [Hash] parameters used to resolve output file paths and contents.
+    def parameters
+      super.merge(
+        collection_path:,
+        data_contents:,
+        object_path:,
+        version_string:
+      )
+    end
+
+    private
+
+    def collection
+      @collection ||= tools.string_tools.pluralize(data_type)
+    end
+
+    def collection_path
+      if version
+        File.join(docs_path, "_#{collection}", "version--#{version}")
+      else
+        File.join(docs_path, "_#{collection}")
+      end
+    end
+
+    def data_contents
+      YAML.safe_dump(
+        object
+          .as_json
+          .merge(
+            'version'  => version_string,
+            'checksum' => object.checksum
+          )
+      )
+    end
+
+    def data_type
+      @data_type ||=
+        object
+        .class
+        .name
+        .split('::')
+        .last
+        .sub(/Object\z/, '')
+        .then { |str| tools.string_tools.underscore(str) }
+        .then { |str| str == 'root' ? 'namespace' : str }
+    end
+
+    def object_path = object.data_path
+
+    def version_string
+      return options[:version] if options[:version]
+
+      '*'
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/generators/reference_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/generators'
+
+module SleepingKingStudios::Docs::Jekyll::Generators
+  # Generator class for writing reference data and files to the filesystem.
+  class ReferenceGenerator < SleepingKingStudios::Docs::Jekyll::Generators::DataGenerator # rubocop:disable Layout/LineLength
+    REFERENCE_TEMPLATE = Cuprum::Cli::Files::Templates::StringTemplate.new(
+      engine:       Cuprum::Cli::Files::Engines::ERB,
+      raw_template: <<~MARKDOWN
+        ---
+        data_path: "<%= object_path %>"
+        version: "<%= version_string %>"
+        ---
+
+        {% include reference/<%= data_type %>.md %}
+      MARKDOWN
+    ).freeze
+    private_constant :REFERENCE_TEMPLATE
+
+    output '%<reference_path>s/%<object_path>s.md',
+      key:      :reference,
+      template: REFERENCE_TEMPLATE
+
+    # @return [Hash] parameters used to resolve output file paths and contents.
+    def parameters
+      super.merge(data_type:, reference_path:, version_string:)
+    end
+
+    private
+
+    def reference_path
+      if version
+        File.join(docs_path, 'versions', version, 'reference')
+      else
+        File.join(docs_path, 'reference')
+      end
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/generators/version_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/generators'
+
+module SleepingKingStudios::Docs::Jekyll::Generators
+  # Generator class for writing versions as Jekyll collection items.
+  class VersionGenerator < Cuprum::Cli::Files::Generator
+    TEMPLATE = Cuprum::Cli::Files::Templates::StringTemplate.new(
+      engine:       Cuprum::Cli::Files::Engines::ERB,
+      raw_template: <<~TEMPLATE
+        ---
+        version: "<%= version %>"
+        sortable: "<%= sortable_version %>"
+      TEMPLATE
+    ).freeze
+    private_constant :TEMPLATE
+
+    option :docs_path,
+      type:    :string,
+      default: 'docs'
+
+    option :version,
+      type:     :string,
+      required: true
+
+    output '%<docs_path>s/_versions/%<version_slug>s.yml',
+      template: TEMPLATE
+
+    # @return [Hash] parameters used to resolve output file paths and
+    #   contents.
+    def parameters
+      super.merge(sortable_version:, version_slug:)
+    end
+
+    # Generates a sortable copy of the version string.
+    #
+    # Splits the string into `.`-delineated segments, then left-pads each
+    # numeric segment with zeroes to a length of 3.
+    #
+    # @return [String] the sortable version string.
+    #
+    # @example
+    #   generator =
+    #     SleepingKingStudios::Docs::Jekyll::Generators::Generator
+    #     .new(version: '0.10.2')
+    #
+    #   generator.sortable_version
+    #   #=> '000.010.002'
+    def sortable_version
+      version
+        .split('.')
+        .map do |segment|
+          next segment unless segment =~ /\A\d+\z/
+
+          format('%03i', segment)
+        end
+        .join('.')
+    end
+
+    # @return [String] the version string, with `.` characters converted to
+    #   dashes for use in file names.
+    def version_slug
+      version.tr('.', '-')
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll/generators.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll'
+
+module SleepingKingStudios::Docs::Jekyll
+  # Namespace for data generators, which write docs to the filesystem.
+  module Generators
+    autoload :DataGenerator,
+      'sleeping_king_studios/docs/jekyll/generators/data_generator'
+    autoload :ReferenceGenerator,
+      'sleeping_king_studios/docs/jekyll/generators/reference_generator'
+    autoload :VersionGenerator,
+      'sleeping_king_studios/docs/jekyll/generators/version_generator'
+  end
+end

data/lib/sleeping_king_studios/docs/jekyll.rb

@@ -5,6 +5,31 @@ require 'sleeping_king_studios/docs'
 module SleepingKingStudios::Docs
   # Namespace for working with Jekyll-specific functionality.
   module Jekyll
-    autoload :Plugins, 'sleeping_king_studios/docs/jekyll/plugins'
+    autoload :Commands,   'sleeping_king_studios/docs/jekyll/commands'
+    autoload :Generators, 'sleeping_king_studios/docs/jekyll/generators'
+    autoload :Plugins,    'sleeping_king_studios/docs/jekyll/plugins'
+
+    # @return [Array<Class>] the default commands for generating documentation
+    #   for a Jekyll site.
+    def self.commands
+      [
+        SleepingKingStudios::Docs::Jekyll::Commands::Clobber,
+        SleepingKingStudios::Docs::Jekyll::Commands::Check,
+        SleepingKingStudios::Docs::Jekyll::Commands::DocumentVersion,
+        SleepingKingStudios::Docs::Jekyll::Commands::Generate,
+        SleepingKingStudios::Docs::Jekyll::Commands::Update
+      ]
+    end
+
+    # @return [Array<Class>] the default commands for installing a Jekyll
+    #   documentation site.
+    def self.install_commands
+      [
+        SleepingKingStudios::Docs::Jekyll::Commands::BackfillVersions,
+        SleepingKingStudios::Docs::Jekyll::Commands::Install,
+        SleepingKingStudios::Docs::Jekyll::Commands::InstallTemplates,
+        SleepingKingStudios::Docs::Jekyll::Commands::InstallWorkflow
+      ]
+    end
   end
 end

data/lib/sleeping_king_studios/docs/version.rb

@@ -11,7 +11,7 @@ module SleepingKingStudios
       # Major version.
       MAJOR = 0
       # Minor version.
-      MINOR = 2
+      MINOR = 3
       # Patch version.
       PATCH = 0
       # Prerelease version.