sleeping_king_studios-docs 0.2.0 → 0.3.0

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

@@ -1,268 +0,0 @@
-# frozen_string_literal: true
-
-require 'cuprum/command'
-require 'sleeping_king_studios/tools/toolbelt'
-
-require 'sleeping_king_studios/docs/commands'
-
-module SleepingKingStudios::Docs::Commands
-  # Generates YARD documentation files.
-  class Generate < SleepingKingStudios::Docs::Commands::Generators::Base # rubocop:disable Metrics/ClassLength
-    # @overload initialize(docs_path:, **options)
-    #   @param docs_path [String] the directory path for generating the
-    #     documentation files.
-    #   @param options [Hash] the configured options for the generator.
-    #
-    #   @option options dry_run [Boolean] if true, does not make any changes to
-    #     the filesystem.
-    #   @option options force [Boolean] if true, overwrites any existing files.
-    #   @option options version [String] the code version for the generated
-    #     documentation.
-    #   @option options verbose [Boolean] if true, prints status messages to
-    #     STDOUT.
-    def initialize(
-      docs_path:,
-      error_stream:  $stderr,
-      output_stream: $stdout,
-      **options
-    )
-      super(docs_path:, **options)
-
-      @error_stream  = error_stream
-      @output_stream = output_stream
-    end
-
-    private
-
-    attr_reader :failures
-
-    def build_constant(native:)
-      SleepingKingStudios::Docs::Data::ConstantObject.new(native:)
-    end
-
-    def build_class(native:)
-      SleepingKingStudios::Docs::Data::ClassObject.new(native:)
-    end
-
-    def build_method(native:)
-      SleepingKingStudios::Docs::Data::MethodObject.new(native:)
-    end
-
-    def build_module(native:)
-      SleepingKingStudios::Docs::Data::ModuleObject.new(native:)
-    end
-
-    def build_root_namespace(native:)
-      SleepingKingStudios::Docs::Data::RootObject.new(native:)
-    end
-
-    def data_command
-      @data_command ||=
-        SleepingKingStudios::Docs::Commands::Generators::DataGenerator
-        .new(docs_path:, **options)
-    end
-
-    def generate_classes
-      puts "\nGenerating Classes:" if verbose? && !registry_classes.empty?
-
-      registry_classes.each do |native|
-        data_object = build_class(native:)
-
-        puts "- #{data_object.name}" if verbose?
-
-        generate_data_file(data_object:)
-        generate_reference_file(data_object:)
-      end
-    end
-
-    def generate_constants
-      puts "\nGenerating Constants:" if verbose? && !registry_constants.empty?
-
-      registry_constants.each do |native|
-        data_object = build_constant(native:)
-
-        puts "- #{data_object.name}" if verbose?
-
-        generate_data_file(data_object:)
-      end
-    end
-
-    def generate_data_file(data_object:, **options)
-      report_result(
-        command:     data_command,
-        data_object:,
-        result:      data_command.call(data_object:, **options),
-        **options
-      )
-    end
-
-    def generate_methods
-      puts "\nGenerating Methods:" if verbose? && !registry_methods.empty?
-
-      registry_methods.each do |native|
-        data_object = build_method(native:)
-
-        puts "- #{data_object.name}" if verbose?
-
-        generate_data_file(data_object:)
-      end
-    end
-
-    def generate_modules
-      puts "\nGenerating Modules:" if verbose? && !registry_modules.empty?
-
-      registry_modules.each do |native|
-        data_object = build_module(native:)
-
-        puts "- #{data_object.name}" if verbose?
-
-        generate_data_file(data_object:)
-        generate_reference_file(data_object:)
-      end
-    end
-
-    def generate_reference_file(data_object:, **options)
-      report_result(
-        command:     reference_command,
-        data_object:,
-        result:      reference_command.call(
-          data_object:,
-          **options
-        ),
-        **options
-      )
-    end
-
-    def generate_root_namespace
-      puts 'Generating Root Namespace:' if verbose?
-
-      data_object = build_root_namespace(native: registry_root)
-
-      puts '- root namespace' if verbose?
-
-      generate_data_file(data_object:, data_type: :namespace)
-    end
-
-    def parse_registry(file_path:)
-      SleepingKingStudios::Docs::Commands::Parse.new.call(file_path)
-    end
-
-    def process(file_path: nil)
-      step { parse_registry(file_path:) }
-
-      @failures = []
-
-      generate_root_namespace
-      generate_classes
-      generate_constants
-      generate_methods
-      generate_modules
-
-      report_all_failures
-
-      nil
-    end
-
-    def puts(string)
-      output_stream.puts(string)
-    end
-
-    def reference_command
-      @reference_command ||=
-        SleepingKingStudios::Docs::Commands::Generators::ReferenceGenerator
-        .new(docs_path:, **options)
-    end
-
-    def registry
-      SleepingKingStudios::Docs::Registry.instance
-    end
-
-    def registry_classes
-      registry
-        .select { |obj| obj.type == :class }
-        .reject { |obj| obj.tags.any? { |tag| tag.tag_name == 'private' } }
-        .sort_by(&:path)
-    end
-
-    def registry_constants
-      registry
-        .select { |obj| obj.type == :constant && obj.visibility == :public }
-        .reject { |obj| obj.tags.any? { |tag| tag.tag_name == 'private' } }
-        .sort_by(&:path)
-    end
-
-    def registry_methods
-      registry
-        .select { |obj| obj.type == :method && obj.visibility == :public }
-        .reject { |obj| obj.tags.any? { |tag| tag.tag_name == 'private' } }
-        .reject(&:is_alias?)
-        .sort_by(&:path)
-    end
-
-    def registry_modules
-      registry
-        .select { |obj| obj.type == :module }
-        .reject { |obj| obj.tags.any? { |tag| tag.tag_name == 'private' } }
-        .sort_by(&:path)
-    end
-
-    def registry_root
-      registry
-        .find { |obj| obj.type == :root }
-    end
-
-    def report_all_failures
-      return if failures.empty?
-      return unless verbose?
-
-      warn "\nFailures:"
-
-      failures.each do |failure|
-        report_failure(**failure, nested: true)
-      end
-    end
-
-    def report_failure(file_path:, result:, nested: false)
-      message = nested ? '  - ' : ''
-      message +=
-        "FAILURE: unable to write file to #{file_path} - " \
-        "#{result.error.class}: #{result.error.message}"
-
-      warn message
-    end
-
-    def report_result(command:, data_object:, result:, data_type: nil) # rubocop:disable Metrics/MethodLength
-      data_type ||= data_object_type(data_object:)
-      file_path   = command.file_path(
-        data_object:,
-        data_type:
-      )
-
-      if result.success?
-        report_success(file_path:)
-      else
-        failures << { file_path:, result: }
-
-        report_failure(file_path:, result:, nested: verbose?)
-      end
-
-      result
-    end
-
-    def report_success(file_path:)
-      return unless verbose?
-
-      message = "  - SUCCESS: file written to #{file_path}"
-
-      puts message
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
-
-    def warn(string)
-      error_stream.puts(string)
-    end
-  end
-end

data/lib/sleeping_king_studios/docs/commands/generators/base.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-require 'cuprum/command'
-require 'cuprum/exception_handling'
-require 'sleeping_king_studios/tools/toolbelt'
-
-require 'sleeping_king_studios/docs/commands/generators'
-
-module SleepingKingStudios::Docs::Commands::Generators
-  # Abstract base class for writing generator classes.
-  class Base < Cuprum::Command
-    include Cuprum::ExceptionHandling
-
-    # @param docs_path [String] the directory path for generating the
-    #   documentation files.
-    # @param options [Hash] the configured options for the generator.
-    #
-    # @option options dry_run [Boolean] if true, does not make any changes to
-    #   the filesystem.
-    # @option options force [Boolean] if true, overwrites any existing files.
-    # @option options version [String] the code version for the generated
-    #   documentation.
-    # @option options verbose [Boolean] if true, prints status messages to
-    #   STDOUT.
-    def initialize(docs_path:, **options)
-      super()
-
-      @docs_path = docs_path
-      @options   = default_options.merge(options)
-    end
-
-    # @return [String] the directory path for generating the documentation
-    #   files.
-    attr_reader :docs_path
-
-    # @return [Hash] the configured options for the generator.
-    attr_reader :options
-
-    # @return [Boolean] if true, does not make any changes to the filesystem.
-    def dry_run?
-      @options[:dry_run]
-    end
-
-    # @return [Boolean] if true, overwrites any existing files.
-    def force?
-      @options[:force]
-    end
-
-    # @return [String] the relative path to the Jekyll templates for each data
-    #   type.
-    def template_path
-      @options.fetch(:template_path, 'reference')
-    end
-
-    # @return [Boolean] if true, prints status messages to STDOUT.
-    def verbose?
-      @options[:verbose]
-    end
-
-    # @return [String] the code version for the generated documentation.
-    def version
-      @options[:version]
-    end
-
-    private
-
-    attr_reader :error_stream
-
-    attr_reader :output_stream
-
-    def data_object_type(data_object:)
-      data_object
-        .class
-        .name
-        .split('::')
-        .last
-        .then { |str| str[0...-6] }
-        .then { |str| tools.string_tools.underscore(str) }
-    end
-
-    def default_options
-      {
-        dry_run: false,
-        force:   false,
-        verbose: false
-      }
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
-
-    def version_string
-      version || '*'
-    end
-  end
-end

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

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-
-require 'sleeping_king_studios/tools/toolbelt'
-
-require 'sleeping_king_studios/docs/commands/generators'
-
-module SleepingKingStudios::Docs::Commands::Generators
-  # Generator for writing data files.
-  class DataGenerator < SleepingKingStudios::Docs::Commands::Generators::Base
-    # Determines the generated file path for the given data object.
-    #
-    # @param data_object [SleepingKingStudios::Docs::Data::Base] the data object
-    #   for which the file is generated.
-    # @param data_type [String, Symbol] the type of data file to generate.
-    #
-    # @return [String] the qualified path to the generated file.
-    def file_path(data_object:, data_type: nil)
-      data_type ||= data_object_type(data_object:)
-
-      File.join(dir_path(data_type), "#{data_object.data_path}.yml")
-    end
-
-    private
-
-    def dir_path(data_type)
-      scope = "_#{tools.string_tools.pluralize(data_type.to_s)}"
-
-      if version
-        File.join(docs_path, scope, "version--#{version}")
-      else
-        File.join(docs_path, scope)
-      end
-    end
-
-    def file_data(data_object:)
-      data_object
-        .as_json
-        .merge('version' => version_string)
-    end
-
-    def process(data_object:, data_type: nil)
-      data        = file_data(data_object:)
-      data_type ||= data_object_type(data_object:)
-
-      return success(nil) if dry_run?
-
-      write_command.call(
-        contents:  YAML.dump(data),
-        file_path: file_path(
-          data_object:,
-          data_type:
-        )
-      )
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
-
-    def write_command
-      @write_command ||=
-        SleepingKingStudios::Docs::Commands::WriteFile
-        .new(force: force?)
-    end
-  end
-end

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

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require 'sleeping_king_studios/docs/commands/generators'
-
-module SleepingKingStudios::Docs::Commands::Generators
-  # Generator for writing reference files.
-  class ReferenceGenerator <
-        SleepingKingStudios::Docs::Commands::Generators::Base
-    # @overload file_path(data_object:)
-    #   Determines the generated file path for the given data object.
-    #
-    #   @param data_object [SleepingKingStudios::Docs::Data::Base] the data
-    #     object for which the file is generated.
-    #
-    #   @return [String] the qualified path to the generated file.
-    def file_path(data_object:, data_type: nil) # rubocop:disable Lint/UnusedMethodArgument
-      File.join(dir_path, "#{data_object.data_path}.md")
-    end
-
-    private
-
-    def dir_path
-      if version
-        File.join(docs_path, 'versions', version, 'reference')
-      else
-        File.join(docs_path, 'reference')
-      end
-    end
-
-    def process(data_object:, data_type: nil)
-      data_type ||= data_object_type(data_object:)
-      contents    = template(data_object:, data_type:)
-
-      return success(nil) if dry_run?
-
-      write_command.call(
-        contents:,
-        file_path: file_path(data_object:)
-      )
-    end
-
-    def template(data_object:, data_type:)
-      <<~MARKDOWN
-        ---
-        data_path: "#{data_object.data_path}"
-        version: "#{version_string}"
-        ---
-
-        {% include #{template_path}/#{data_type}.md %}
-      MARKDOWN
-    end
-
-    def write_command
-      @write_command ||=
-        SleepingKingStudios::Docs::Commands::WriteFile
-        .new(force: force?)
-    end
-  end
-end

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

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-require 'sleeping_king_studios/docs/commands'
-
-module SleepingKingStudios::Docs::Commands
-  # Namespace for generator commands, which write docs to the filesystem.
-  module Generators
-    autoload :Base,
-      'sleeping_king_studios/docs/commands/generators/base'
-    autoload :DataGenerator,
-      'sleeping_king_studios/docs/commands/generators/data_generator'
-    autoload :ReferenceGenerator,
-      'sleeping_king_studios/docs/commands/generators/reference_generator'
-  end
-end