sleeping_king_studios-docs 0.2.0 → 0.3.0

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

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Generates pinned documentation for the specified project version.
+  #
+  # - Adds the version to the _versions collection.
+  # - Generates reference documentation for the version.
+  # - Copies all static documentation files to the respective versions/*
+  #   subdirectory.
+  class DocumentVersion < 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
+
+    argument :version, type: :string, required: true
+
+    option :docs_path, default: 'docs'
+
+    option :dry_run,   type: :boolean, default: false
+
+    full_name 'docs:jekyll:document_version'
+
+    description 'Generates pinned documentation for the specified version'
+
+    private
+
+    def copy_static_file(original_path)
+      relative_path = original_path.sub(%r{#{docs_path}/}, '')
+      updated_path  = File.join(docs_path, 'versions', version, relative_path)
+
+      contents       = file_system.read_file(original_path)
+      metadata, text = step { extract_front_matter(contents) }
+      metadata       = update_metadata(metadata:, relative_path:)
+      contents       = generate_contents(metadata:, text:)
+
+      files = step { write_static_file(contents:, updated_path:) }
+
+      @files.concat(files)
+    end
+
+    def copy_static_files
+      say "\nCopying static documentation..."
+      say("\n", verbose: true)
+
+      find_static_docs.each { |file_path| copy_static_file(file_path) }
+    end
+
+    def default_breadcrumbs_for(relative_path)
+      *dir_path, _ = relative_path.split(File::SEPARATOR)
+
+      return [] if dir_path.empty?
+
+      dir_path
+        .each
+        .map do |segment, index|
+          name = tools.string_tools.camelize(segment.tr('-_', ''))
+          path = "#{File::SEPARATOR}#{File.join(dir_path[0..index])}"
+
+          { 'name' => name, 'path' => path }
+        end
+    end
+
+    def exclude_static_file?(file_path)
+      return false if file_path == "#{docs_path}/reference/index.md"
+
+      file_path.start_with?("#{docs_path}/_includes/") ||
+        file_path.start_with?("#{docs_path}/reference") ||
+        file_path.start_with?("#{docs_path}/versions")
+    end
+
+    def extract_front_matter(contents)
+      return [{}, contents] unless contents.start_with?("---\n")
+
+      match = /^---\n$/.match(contents[4..])
+
+      return [{}, contents] unless match
+
+      text = match.post_match
+      yaml = YAML.safe_load(match.pre_match) || {}
+
+      [yaml, text]
+    end
+
+    def generate_contents(metadata:, text:)
+      "#{YAML.safe_dump(metadata)}---\n#{text}"
+    end
+
+    def generate_reference_files # rubocop:disable Metrics/MethodLength
+      say "\nGenerating data and reference files:"
+      say("\n", verbose: true)
+
+      files = step do
+        SleepingKingStudios::Docs::Jekyll::Commands::Generate
+          .new(file_system:, standard_io:)
+          .call(
+            docs_path:,
+            dry_run:   dry_run?,
+            quiet:     quiet?,
+            verbose:   verbose?,
+            version:
+          )
+      end
+
+      @files.concat(files)
+    end
+
+    def generate_version # rubocop:disable Metrics/MethodLength
+      say "\nGenerating version file:"
+      say("\n", verbose: true)
+
+      files = step do
+        SleepingKingStudios::Docs::Jekyll::Generators::VersionGenerator
+          .new(
+            file_system:,
+            standard_io:,
+            docs_path:,
+            dry_run:     dry_run?,
+            quiet:       quiet?,
+            verbose:     verbose?,
+            version:
+          )
+          .call
+      end
+
+      @files.concat(files)
+    end
+
+    def find_static_docs
+      file_system
+        .each_file("#{docs_path}/**/*.md")
+        .reject { |file_path| exclude_static_file?(file_path) }
+        .to_a
+    end
+
+    def process
+      say "Generating pinned documentation for version #{version}"
+
+      @files = []
+
+      step { generate_reference_files }
+
+      step { generate_version }
+
+      step { copy_static_files }
+
+      say "\nSuccess!"
+
+      @files
+    end
+
+    def top_level_breadcrumb?(obj)
+      obj.is_a?(Hash) && obj['path'] == File::SEPARATOR
+    end
+
+    def version_breadcrumbs # rubocop:disable Metrics/MethodLength
+      @version_breadcrumbs ||= [
+        {
+          'name' => 'Documentation',
+          'path' => File::SEPARATOR
+        },
+        {
+          'name' => 'Versions',
+          'path' => "#{File::SEPARATOR}versions"
+        },
+        {
+          'name' => "Version #{version}",
+          'path' => "#{File::SEPARATOR}#{File.join('versions', version)}"
+        }
+      ]
+    end
+
+    def update_breadcrumbs(breadcrumbs:, relative_path:)
+      prefix      = "#{File::SEPARATOR}#{File.join('versions', version)}"
+      breadcrumbs = breadcrumbs[1..] if top_level_breadcrumb?(breadcrumbs.first)
+      breadcrumbs = breadcrumbs.map do |hsh|
+        hsh.merge('path' => File.join(prefix, hsh['path']))
+      end
+
+      if breadcrumbs.empty? && relative_path == 'index.md'
+        return version_breadcrumbs[...-1]
+      end
+
+      version_breadcrumbs + breadcrumbs
+    end
+
+    def update_metadata(metadata:, relative_path:)
+      breadcrumbs = update_breadcrumbs(
+        breadcrumbs:   metadata.fetch(
+          'breadcrumbs',
+          default_breadcrumbs_for(relative_path)
+        ),
+        relative_path:
+      )
+
+      metadata.merge('breadcrumbs' => breadcrumbs, 'version' => version)
+    end
+
+    def write_static_file(contents:, updated_path:) # rubocop:disable Metrics/MethodLength
+      Cuprum::Cli::Files::Generators::BasicGenerator
+        .new(
+          file_system:,
+          standard_io:,
+          contents:,
+          dry_run:     dry_run?,
+          file_path:   updated_path,
+          quiet:       quiet?,
+          verbose:     verbose?
+        )
+        .call
+    end
+  end
+end

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