sleeping_king_studios-docs 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 187804266272946364341348fd3889893752cc218af1049326fa56856c7f8751
-  data.tar.gz: 2eed4cc2aea0b359d1487b0c94b5c1ab860334021093546cb8748352dac5cc44
+  metadata.gz: 692df3daacc487bdd141df14405aed3f6c9378344a9544117e97d753a1440ae9
+  data.tar.gz: 2a0cd40acc165ef9cb9b5d851002f021aa5472d0ab2b7104c98cf8a2dd920c97
 SHA512:
-  metadata.gz: 7908bf7a9412828c78783ca387450ef9ea5029d35495dcb3575e5eff7b4c99090c98b00d1cba7f0754f996bca9e11dde4361b2c9a47ac47a15764eafe72b4a79
-  data.tar.gz: 186ec6c0d7a9a711579d6b4d0f4d444c9e03bf3f3be28ec7072df90e64de1827fe99ce4923811d2127a30319afc90a08c2bc094dbe2dcd30f43f1e5e0b4da5ff
+  metadata.gz: eff118f9be58d603fcee02e2325ea08d3c52857baf6c2537a2436dd95f59f7d26871e4d280ce87c86df42e240754b6fabb628c2a59e87a63f423cdc7d6f92a82
+  data.tar.gz: e6bf2e33811d5f5803f171853bc2510af44f6f11506ed57f18904b80033e9f7ac7b89cf105ced7768112ece430ceb2db66996cf13f95a08e05151b39e49cbc79

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+# 0.3.0
+
+Removed support for Ruby 3.1.
+
+> **Warning**
+>
+> CLI commands are now namespaced in preparation for adding support for non-Jekyll site generators.
+
+> **Upgrade Notes**
+>
+> Remove `load 'sleeping_king_studios/docs/tasks.rb'` from your `.thor` file and add:
+>
+> ```ruby
+> require 'sleeping_king_studios/docs/jekyll'
+>
+> require 'cuprum/cli/integrations/thor/registry'
+>
+> registry = Cuprum::Cli::Integrations::Thor::Registry.new
+>
+> # Docs Commands
+> registry.register SleepingKingStudios::Docs::Jekyll.commands
+>
+> # Installation Commands (Creating or Updating Projects)
+> registry.register SleepingKingStudios::Docs::Jekyll.install_commands
+> ```
+>
+> Backfill any existing versions using `thor docs:jekyll:backfill_versions`.
+
+## Commands
+
+Added dependency on `cuprum/cli` gem.
+
+Refactored CLI Commands:
+
+- Installation commands now use `Cuprum::Cli`.
+- Installation commands moved to `Docs::Jekyll::Commands` namespace.
+- Reference commands refactored and moved to `Docs::Jekyll::Commands` namespace.
+
+Updated file templates.
+
+## Jekyll
+
+Updated site configuration to include project metadata, including name, description, and repository information.
+
+Added `_versions` collection for tracking documented versions.
+
+Added updated site templates.
+
+- Updated page breadcrumbs to be relative to the root path.
+- Updated named headers to reference project metadata.
+- Updated versions page to enumerate documented versions.
+
 # 0.2.1
 
 Added support for Ruby 4.0.

data/README.md

@@ -13,7 +13,7 @@ Tools for generating a versioned documentation site from YARD docs.
 
 ### Compatibility
 
-SleepingKingStudios::Yard is tested against Ruby (MRI) 3.1 through 3.4.
+SleepingKingStudios::Yard is tested against Ruby (MRI) 3.2 through 4.0.
 
 ### Documentation
 
@@ -21,7 +21,7 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2022-2025 Rob Smith
+Copyright (c) 2022-2026 Rob Smith
 
 SleepingKingStudios::Docs is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -42,9 +42,11 @@ Please note that the `SleepingKingStudios::Docs` project is released with a [Con
 Add the docs dependencies to your Gemfile:
 
 ```ruby
+# Ensure that the CLI tool is available in development environment.
+gem 'sleeping_king_studios-docs', groups: %w[docs development]
+
 group :docs do
   gem 'jekyll'
-  gem 'sleeping_king_studios-docs'
   gem 'webrick'
   gem 'yard',  require: false
 end
@@ -57,7 +59,17 @@ Generate or update your `tasks.thor` file:
 ```ruby
 # frozen_string_literal: true
 
-load 'sleeping_king_studios/docs/tasks.rb'
+require 'cuprum/cli/integrations/thor/registry'
+
+registry = Cuprum::Cli::Integrations::Thor::Registry.new
+
+require 'sleeping_king_studios/docs/jekyll'
+
+# Docs Commands
+registry.register SleepingKingStudios::Docs::Jekyll.commands
+
+# Installation Commands (Creating or Updating Projects)
+registry.register SleepingKingStudios::Docs::Jekyll.install_commands
 ```
 
 ### Installation Script
@@ -65,37 +77,41 @@ load 'sleeping_king_studios/docs/tasks.rb'
 Use the installation script to quickly install the Jekyll application:
 
 ```bash
-bundle exec thor docs:install --name="Orichalcum" --description="A real gem." --repository="www.example.com"
+bundle exec thor docs:jekyll:install
 ```
 
 You can also install a GitHub pages workflow to automatically deploy to GitHub Pages. Make sure that Pages is configured for your repository to deploy from a GitHub action.
 
 ```bash
-bundle exec thor docs:install:workflow
+bundle exec thor docs:jekyll:install_workflow
 ```
 
 ## Generating Documentation
 
-Use the [Thor CLI](https://www.sleepingkingstudios.com/sleeping_king_studios-docs/tasks#documentation) to generate and update the reference documentation for your project.
+Use the [Thor CLI](https://www.sleepingkingstudios.com/sleeping_king_studios-docs/commands) to generate and update the reference documentation for your project.
 
-The `docs:generate` task will generate the documentation files for each Ruby file in your project. It does not update any existing files by default, so if you have made changes to existing code use the `docs:update` command or use the `--force` command line option.
+The `docs:jekyll:generate` task will generate the documentation files for each Ruby file in your project.
 
 ```bash
-bundle exec thor docs:generate
+bundle exec thor docs:jekyll:generate
 ```
 
-The `docs:update` task will generate and updates th documentation files for each Ruby file in your project. It will update any existing documentation files.
+The `docs:jekyll:update` task will generate and update the documentation files for each Ruby file in your project. It will update any existing documentation files and remove old files that no longer correspond to objects or methods in the code.
 
 ```bash
-bundle exec thor docs:update
+bundle exec thor docs:jekyll:update
 ```
 
 ### Versioned Documentation
 
-You can pass a `--version` flag to the `docs:generate` or `docs:update` tasks, indicating that the generated documentation is for a specific version of the software. This is recommended for each major and minor release; patch-level changes may or may not need to be documented depending on the degree of change.
+You can generate reference docs and copy non-release documentation into the newly created version scope using the `document_version` command. This is recommended for each major and minor release; patch-level changes may or may not need to be documented depending on the degree of change.
 
 ```bash
-bundle exec thor docs:generate --version="1.2.3"
+bundle exec thor docs:jekyll:document_version "1.2.3"
 ```
 
-Any non-reference documentation should be copied into the newly created version scope. Make sure to update the `versions/index.md` file to link the new scope.
+You can also pass a `--version` flag to the `docs:jekyll:generate` or `docs:jekyll:update` tasks, indicating that the generated documentation is for a specific version of the software.
+
+```bash
+bundle exec thor docs:jekyll:generate --version="1.2.3"
+```

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

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'json'
+
+require 'plumbum'
 require 'sleeping_king_studios/tools/toolbelt'
 
 require 'sleeping_king_studios/docs/data'
@@ -9,11 +13,18 @@ module SleepingKingStudios::Docs::Data
   #
   # @abstract
   class Base
+    include Plumbum::Consumer
+    prepend Plumbum::Parameters
+
+    dependency :registry,
+      default: SleepingKingStudios::Docs::Yard::Registry::EMPTY
+
+    provider SleepingKingStudios::Docs::Yard::Registry.provider
+
     # @param native [YARD::Tags::Tag] the YARD object representing the
     #   documented object.
     def initialize(native:)
-      @native   = native
-      @registry = SleepingKingStudios::Docs::Registry.instance
+      @native = native
     end
 
     # Generates a JSON-compatible representation of the object.
@@ -23,12 +34,21 @@ module SleepingKingStudios::Docs::Data
       {}
     end
 
+    # Generates an MD5 checksum of the data properties.
+    #
+    # The checksum is stored as a Base64-encoded String.
+    #
+    # @return [String] the checksum value.
+    def checksum
+      @checksum ||= Digest::MD5.base64digest(
+        "#{self.class.name}:#{JSON.fast_generate(as_json)}"
+      )
+    end
+
     private
 
     attr_reader :native
 
-    attr_reader :registry
-
     def empty?(value)
       return true if value.nil?
 

data/lib/sleeping_king_studios/docs/data/constant_object.rb

@@ -102,6 +102,30 @@ module SleepingKingStudios::Docs::Data
       @parent_path = parent_object.data_path
     end
 
+    # @return [true, false] true if the constant visibility is private, or if
+    #   the constant (or its namespace) has a @private tag.
+    def private?
+      return true if native.visibility == :private
+
+      object = native
+
+      while object
+        return true if object.tags.any? { |tag| tag.tag_name == 'private' }
+
+        object = object.parent
+      end
+
+      false
+    end
+
+    # @return [true, false] true if the constant visibility is public, and the
+    #   constant (and its namespace) does not have a @private tag.
+    def public?
+      return false unless native.visibility == :public
+
+      !private?
+    end
+
     # A short description of the constant.
     #
     # The first part of the constant description, separated by the first

data/lib/sleeping_king_studios/docs/data/metadata.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 require 'sleeping_king_studios/docs/data'
 
 module SleepingKingStudios::Docs::Data

data/lib/sleeping_king_studios/docs/data/method_object.rb

@@ -240,6 +240,38 @@ module SleepingKingStudios::Docs::Data
       @parent_path = parent_object.data_path
     end
 
+    # @return [true, false] true if the method visibility is protected, and the
+    #   method (and its namespace) does not have a @private tag.
+    def protected?
+      return false unless native.visibility == :protected
+
+      !private?
+    end
+
+    # @return [true, false] true if the method visibility is private, or if the
+    #   method (or its namespace) has a @private tag.
+    def private?
+      return true if native.visibility == :private
+
+      object = native
+
+      while object
+        return true if object.tags.any? { |tag| tag.tag_name == 'private' }
+
+        object = object.parent
+      end
+
+      false
+    end
+
+    # @return [true, false] true if the method visibility is public, and the
+    #   method (and its namespace) does not have a @private tag.
+    def public?
+      return false unless native.visibility == :public
+
+      !private?
+    end
+
     # The documented raised exceptions of the method.
     #
     # Each raised exception is a Hash with the following keys:

data/lib/sleeping_king_studios/docs/data/module_object.rb

@@ -117,7 +117,7 @@ module SleepingKingStudios::Docs::Data
     #
     # @return [Array<String>] the list of files.
     def files
-      @files ||= native.files.map(&:first)
+      @files ||= native.files.map(&:first).uniq
     end
 
     # A list of the modules that are included in the original module.

data/lib/sleeping_king_studios/docs/data/namespace_object.rb

@@ -218,6 +218,30 @@ module SleepingKingStudios::Docs::Data
       @name ||= native.path
     end
 
+    # @return [true, false] true if the namespace visibility is private, or if
+    #   the namespace (or its parent namespace) has a @private tag.
+    def private?
+      return true if native.visibility == :private
+
+      object = native
+
+      while object
+        return true if object.tags.any? { |tag| tag.tag_name == 'private' }
+
+        object = object.parent
+      end
+
+      false
+    end
+
+    # @return [true, false] true if the namespace visibility is public, and the
+    #   constant (and its parent namespace) does not have a @private tag.
+    def public?
+      return false unless native.visibility == :public
+
+      !private?
+    end
+
     # The name of the namespace in url-safe format.
     #
     # @return [String] the namespace name.
@@ -359,8 +383,8 @@ module SleepingKingStudios::Docs::Data
 
     def public_attribute?(options)
       options
-        .values
-        .select { |value| value.is_a?(YARD::CodeObjects::MethodObject) }
+        .each_value
+        .grep(YARD::CodeObjects::MethodObject)
         .any? { |obj| !private_method?(obj) }
     end
 

data/lib/sleeping_king_studios/docs/data/see_tags/reference_tag.rb

@@ -60,7 +60,7 @@ module SleepingKingStudios::Docs::Data::SeeTags
 
     def registry_query
       @registry_query ||=
-        SleepingKingStudios::Docs::RegistryQuery.new(registry:)
+        SleepingKingStudios::Docs::Yard::RegistryQuery.new(registry:)
     end
 
     def qualified_path

data/lib/sleeping_king_studios/docs/data/types/type.rb

@@ -12,8 +12,7 @@ module SleepingKingStudios::Docs::Data::Types
 
     # @param name [String] the name of the type.
     def initialize(name:)
-      @name     = name
-      @registry = SleepingKingStudios::Docs::Registry.instance
+      @name = name
     end
 
     # @return [String] the name of the type.
@@ -52,8 +51,8 @@ module SleepingKingStudios::Docs::Data::Types
       return @exists = false if literal? || method?
 
       @exists =
-        SleepingKingStudios::Docs::RegistryQuery
-        .new(registry:)
+        SleepingKingStudios::Docs::Yard::RegistryQuery
+        .new
         .definition_exists?(name)
     end
 
@@ -83,8 +82,6 @@ module SleepingKingStudios::Docs::Data::Types
 
     private
 
-    attr_reader :registry
-
     def inspect_attributes
       "@name=#{name.inspect}"
     end

data/lib/sleeping_king_studios/docs/errors/outdated_documentation.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Error returned when the checked documentation does not match the code.
+  class OutdatedDocumentation < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.outdated_documentation'
+
+    # @param docs_path [String] the path to the generated documentation.
+    # @param version [String, nil] the version of the generated documentation.
+    # @param changed_files [Array<String>] the list of docs files with missing
+    #   or non-matching checksums.
+    # @param extra_files [Array<String>] the list of additional files in the
+    #   docs directory.
+    # @param missing_files [Array<String>] the list of missing docs files based
+    #   on the registered code.
+    def initialize( # rubocop:disable Metrics/MethodLength
+      docs_path:,
+      changed_files: [],
+      extra_files:   [],
+      missing_files: [],
+      version:       nil
+    )
+      @changed_files = changed_files
+      @docs_path     = docs_path
+      @extra_files   = extra_files
+      @missing_files = missing_files
+      @version       = version
+
+      super(
+        changed_files:,
+        docs_path:,
+        extra_files:,
+        message:       default_message,
+        missing_files:,
+        version:
+      )
+    end
+
+    # @return [Array<String>] the list of docs files with missing or
+    #   non-matching checksums.
+    attr_reader :changed_files
+
+    # @return [String] the path to the generated documentation.
+    attr_reader :docs_path
+
+    # @return [Array<String>] the list of additional files in the docs
+    #   directory.
+    attr_reader :extra_files
+
+    # @return [Array<String>] the list of missing docs files based on the
+    #   registered code.
+    attr_reader :missing_files
+
+    # @return [String, nil] the version of the generated documentation.
+    attr_reader :version
+
+    private
+
+    def as_json_data
+      {
+        'changed_files' => changed_files,
+        'docs_path'     => docs_path,
+        'extra_files'   => extra_files,
+        'missing_files' => missing_files,
+        'version'       => version
+      }
+    end
+
+    def default_message
+      'outdated documentation found for ' \
+        "#{version ? "version #{version}" : 'current version'}"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/errors/registry_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Error returned when an invalid registry operation is performed.
+  class RegistryError < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.registry_error'
+  end
+end

data/lib/sleeping_king_studios/docs/errors.rb

@@ -15,5 +15,9 @@ module SleepingKingStudios::Docs
       'sleeping_king_studios/docs/errors/invalid_directory'
     autoload :InvalidFile,
       'sleeping_king_studios/docs/errors/invalid_file'
+    autoload :OutdatedDocumentation,
+      'sleeping_king_studios/docs/errors/outdated_documentation'
+    autoload :RegistryError,
+      'sleeping_king_studios/docs/errors/registry_error'
   end
 end

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require 'cuprum/cli/files/generators'
+
+require 'sleeping_king_studios/docs/jekyll/commands'
+
+module SleepingKingStudios::Docs::Jekyll::Commands
+  # Helper command to populate the versions collection with past version data.
+  class BackfillVersions < Cuprum::Cli::Command # rubocop:disable Metrics/ClassLength
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    MAJOR_VERSION = /\A\d+\z/
+    private_constant :MAJOR_VERSION
+
+    MAJOR_MINOR_VERSION = /\A\d+\.\d+\z/
+    private_constant :MAJOR_MINOR_VERSION
+
+    MAJOR_MINOR_PATCH_VERSION = /\A\d+\.\d+\.\d+(\.)?/
+    private_constant :MAJOR_MINOR_PATCH_VERSION
+
+    NEXT_STEPS_MESSAGE = <<~OUTPUT
+      Next Steps
+
+        Update _config.yml:
+
+        - In %<docs_path>s/_config.yml, add `versions: { output: false }` to `collections`.
+        - In %<docs_path>s/_config.yml, remove `project_metadata.versions`.
+
+        Update _includes/pages/index-versions.md:
+
+        - In %<docs_path>s/_includes/pages/index-versions.md, replace the latest_version check with the following:
+
+        ```ruby
+        {%% assign latest_version = site.versions | sort: "sortable" | map: "version" | last %%}
+        ```
+
+        Update versions/index.md:
+
+        - In %<docs_path>s/versions/index.md, replace the versions loop with the following:
+
+        ```ruby
+        {%% assign versions = site.versions | sort: "sortable" | map: "version" | reverse %%}
+        {%% for version in versions %%}
+        - [Version {{ version }}]({{site.baseurl}}/versions/{{version}})
+        {%%- endfor %%}
+        ```
+    OUTPUT
+    private_constant :NEXT_STEPS_MESSAGE
+
+    full_name 'docs:jekyll:backfill_versions'
+
+    description 'Backfills the versions collection'
+
+    dependency :file_system
+    dependency :standard_io
+
+    option :docs_path, default: 'docs'
+
+    option :dry_run, type: :boolean, default: false
+
+    private
+
+    attr_reader :files
+
+    attr_reader :versions
+
+    def configured_versions
+      say "Checking _config.yml for existing versions...\n\n"
+
+      data = parse_config_file&.dig('project_metadata', 'versions')
+
+      return [] unless data.is_a?(Array)
+
+      say "  Found versions #{data.join(', ')}\n\n"
+
+      data.map(&:to_s)
+    end
+
+    def create_version(version) # rubocop:disable Metrics/MethodLength
+      result =
+        SleepingKingStudios::Docs::Jekyll::Generators::VersionGenerator
+        .new(
+          file_system:,
+          standard_io:,
+          docs_path:,
+          dry_run:     dry_run?,
+          quiet:       quiet?,
+          verbose:     verbose?,
+          version:
+        )
+        .call
+
+      files.concat(result.value) if result.success?
+    end
+
+    def create_versions_directory
+      dir_path = File.join(docs_path, '_versions')
+
+      file_system.create_directory(dir_path, recursive: true) unless dry_run?
+
+      say "Successfully generated versions collection at #{dir_path}.\n\n"
+    end
+
+    def display_message
+      say "\n" unless versions.empty? || verbose?
+
+      say format(NEXT_STEPS_MESSAGE, docs_path:)
+    end
+
+    def parse_config_file
+      raw = read_config_file
+
+      return unless raw
+
+      YAML.safe_load(raw)
+    rescue Psych::SyntaxError => exception
+      file_path = File.join(docs_path, '_config.yml')
+
+      warn \
+        "  Unable to parse config file at #{file_path} - #{exception.class}: " \
+        "#{exception.message}\n\n"
+    end
+
+    def process
+      @files    = []
+      @versions = []
+
+      versions.concat(configured_versions)
+      versions.concat(version_directories)
+
+      step { create_versions_directory }
+
+      versions.compact.uniq.each do |version|
+        step { create_version(version) }
+      end
+
+      display_message
+
+      files
+    end
+
+    def read_config_file
+      file_path = File.join(docs_path, '_config.yml')
+
+      file_system.read_file(file_path)
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileError => exception
+      warn \
+        "  Unable to read config file - #{exception.class}: " \
+        "#{exception.message}\n\n"
+    end
+
+    def version_directories
+      say "Checking versions directory for existing versions...\n\n"
+
+      matching =
+        file_system
+        .each_file("#{docs_path}/versions/*")
+        .select { |file_name| file_system.directory?(file_name) }
+        .map { |file_name| File.basename(file_name) }
+        .select { |segment| version_string?(segment) }
+
+      say "  Found versions #{matching.join(', ')}\n\n" unless matching.empty?
+
+      matching
+    end
+
+    def version_string?(value)
+      MAJOR_VERSION.match?(value) ||
+        MAJOR_MINOR_VERSION.match?(value) ||
+        MAJOR_MINOR_PATCH_VERSION.match?(value)
+    end
+  end
+end