sleeping_king_studios-docs 0.2.1 → 0.3.0

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,9 +11,9 @@ module SleepingKingStudios
       # Major version.
       MAJOR = 0
       # Minor version.
-      MINOR = 2
+      MINOR = 3
       # Patch version.
-      PATCH = 1
+      PATCH = 0
       # Prerelease version.
       PRERELEASE = nil
       # Build metadata.

data/lib/sleeping_king_studios/docs/yard/build.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+require 'sleeping_king_studios/docs/yard'
+
+module SleepingKingStudios::Docs::Yard
+  # Command for creating generic data objects from YARD objects.
+  class Build < Cuprum::Command
+    DATA_TYPES = {
+      YARD::CodeObjects::RootObject     =>
+        SleepingKingStudios::Docs::Data::RootObject,
+      YARD::CodeObjects::ClassObject    =>
+        SleepingKingStudios::Docs::Data::ClassObject,
+      YARD::CodeObjects::ConstantObject =>
+        SleepingKingStudios::Docs::Data::ConstantObject,
+      YARD::CodeObjects::MethodObject   =>
+        SleepingKingStudios::Docs::Data::MethodObject,
+      YARD::CodeObjects::ModuleObject   =>
+        SleepingKingStudios::Docs::Data::ModuleObject
+    }.freeze
+    private_constant :DATA_TYPES
+
+    private
+
+    def process(native)
+      matching = DATA_TYPES.each_key.find { |type| native.is_a?(type) }
+
+      return failure(unknown_type_error(native)) unless matching
+
+      DATA_TYPES[matching].new(native:)
+    end
+
+    def unknown_type_error(native)
+      message =
+        "unable to parse native object #{native.inspect} - no matching data" \
+        "type defined for #{native.class}"
+
+      SleepingKingStudios::Docs::Errors::RegistryError.new(message:)
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/{commands → yard}/parse.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
+require 'cuprum/cli'
 require 'cuprum/command'
+require 'plumbum'
 require 'yard'
 
-require 'sleeping_king_studios/docs/commands'
+require 'sleeping_king_studios/docs/yard'
 
-module SleepingKingStudios::Docs::Commands
+module SleepingKingStudios::Docs::Yard
   # Adds the specified data to the YARD Registry.
   class Parse < Cuprum::Command
+    include Plumbum::Consumer
+    prepend Plumbum::Parameters
+
+    dependency :file_system
+
+    provider Cuprum::Cli::Dependencies.provider
+
     # @!method call
     #   @overload call
     #     Parses the working directory per YARD defaults.
@@ -29,21 +38,19 @@ module SleepingKingStudios::Docs::Commands
     end
 
     def process(path = nil)
-      if path.nil?
-        ::YARD.parse
+      if path
+        step { validate_file_path(path) }
 
-        return success(nil)
+        ::YARD.parse(path)
+      else
+        ::YARD.parse
       end
 
-      step { validate_file_path(path) }
-
-      ::YARD.parse(path)
-
-      success(nil)
+      SleepingKingStudios::Docs::Yard::Registry.build
     end
 
     def validate_file_path(path)
-      return if File.exist?(path)
+      return if file_system.directory?(path) || file_system.file?(path)
 
       failure(file_not_found_error(path))
     end

data/lib/sleeping_king_studios/docs/yard/registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+require 'yard'
+
+require 'sleeping_king_studios/docs/yard'
+
+module SleepingKingStudios::Docs::Yard
+  Registry = ::Data.define(:items)
+
+  # Dependency injection provider wrapping the YARD registry.
+  #
+  # @!attribute [r] items
+  #   @return [Array<YARD::CodeObjects::Base>] the defined YARD objects.
+  class Registry < ::Data
+    include Enumerable
+
+    # @return [SleepingKingStudios::Docs::Yard::Registry] a new registry
+    #   instance wrapping the current YARD state.
+    def self.build
+      new(items: [::YARD::Registry.root, *::YARD::Registry.to_a])
+    end
+
+    # Provides an injectable instance of the repository wrapper.
+    #
+    # @return [Plumbum::Provider<SleepingKingStudios::Docs::Registry>] the
+    #   registry provider.
+    def self.provider
+      @provider ||= Plumbum::OneProvider.new(:registry, write_once: true)
+    end
+
+    # @param items [Array<YARD::CodeObjects::Base>] the defined YARD objects.
+    def initialize(items: [])
+      super
+    end
+
+    # @overload each
+    #   @return [Enumerator] an enumerator that iterates over the registry
+    #     items.
+    #
+    # @overload each(&block)
+    #   @yield [YARD::CodeObjects::Base] each item in the registry.
+    def each(&)
+      block_given? ? items.each(&) : enum_for(:each)
+    end
+
+    alias to_a items
+  end
+
+  class Registry
+    # An empty registry instance.
+    EMPTY = new
+  end
+end

data/lib/sleeping_king_studios/docs/{registry_query.rb → yard/registry_query.rb}

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
+require 'plumbum'
 require 'sleeping_king_studios/docs'
 
-module SleepingKingStudios::Docs
+module SleepingKingStudios::Docs::Yard
   # Checks for the presence of requested data in the YARD registry.
   class RegistryQuery
-    # @param registry [Enumerable] the YARD registry.
-    def initialize(registry:)
-      @registry = registry
-    end
+    include Plumbum::Consumer
+    prepend Plumbum::Parameters
+
+    dependency :registry,
+      default: SleepingKingStudios::Docs::Yard::Registry::EMPTY
+
+    provider SleepingKingStudios::Docs::Yard::Registry.provider
 
     # Checks if the given class method is defined in the registry.
     #
@@ -72,8 +76,6 @@ module SleepingKingStudios::Docs
 
     private
 
-    attr_reader :registry
-
     def legacy_class_method_exists?(method_name)
       method_name = method_name.reverse.sub('::', '.').reverse
 

data/lib/sleeping_king_studios/docs/yard.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Functionality for parsing and querying YARD documentation.
+  module Yard
+    autoload :Build,         'sleeping_king_studios/docs/yard/build'
+    autoload :Parse,         'sleeping_king_studios/docs/yard/parse'
+    autoload :Registry,      'sleeping_king_studios/docs/yard/registry'
+    autoload :RegistryQuery, 'sleeping_king_studios/docs/yard/registry_query'
+  end
+end