sleeping_king_studios-docs 0.1.0

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

@@ -0,0 +1,59 @@
+# 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

@@ -0,0 +1,15 @@
+# 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

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

@@ -0,0 +1,273 @@
+# 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

@@ -0,0 +1,125 @@
+# 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

@@ -0,0 +1,121 @@
+# 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

@@ -0,0 +1,15 @@
+# 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/parse.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'cuprum/command'
+require 'yard'
+
+require 'sleeping_king_studios/docs/commands'
+
+module SleepingKingStudios::Docs::Commands
+  # Adds the specified data to the YARD Registry.
+  class Parse < Cuprum::Command
+    # @!method call
+    #   @overload call
+    #     Parses the working directory per YARD defaults.
+    #
+    #     @return [Cuprum::Result<Module>] an empty result.
+    #
+    #   @overload call(path)
+    #     Parses the given file or directory.
+    #
+    #     @return [Cuprum::Result<nil>] an empty result if the parse is
+    #       successful.
+    #     @return [Cuprum::Result<Cuprum::Error>] a failing result if the file
+    #       or directory path is invalid.
+
+    private
+
+    def file_not_found_error(path)
+      SleepingKingStudios::Docs::Errors::FileNotFound.new(path:)
+    end
+
+    def process(path = nil)
+      if path.nil?
+        ::YARD.parse
+
+        return success(nil)
+      end
+
+      step { validate_file_path(path) }
+
+      ::YARD.parse(path)
+
+      success(nil)
+    end
+
+    def validate_file_path(path)
+      return if File.exist?(path)
+
+      failure(file_not_found_error(path))
+    end
+  end
+end