utopia-project 0.42.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48f72fdf878294e638e5053f5b0e4cdc19e5d1ee28aa1c51732a1ec467c9a9cb
-  data.tar.gz: bfb6d2e71535e496d6f1c42db8a89be441bfc33a881e8e49d00e6bdaea19df00
+  metadata.gz: 7f02594d75aca403abee0bf56e3e2ec4e398a81df172f6c62cf73cdccba11bc5
+  data.tar.gz: bc73b831e8e44df2de6759154a24d91d0d228e062e5c790d5956788ebddc5177
 SHA512:
-  metadata.gz: e2fecc25e48c3573d61fec6db7a8ca9120b6b3580f62a8e7a249b1012b5ba1c88f341831bcb65409af6c1df82512f63fdcd56704ef7e6c5396d38bda110c5196
-  data.tar.gz: e1b11e6f7566973149e116bc0cf8f1c886d269c0d116e1f8e4b2eb357367abc7208adea969db77cb35d399b0f8016e93908fe65867dee8bcaa747851680dab80
+  metadata.gz: 3dd75a8af1c68d0b7d4b64856f569d13468e6b3296303bcad6b02f3595709821c88de4387212aad33a629caa2854b8f5e6ebfdebfe1e0b7a17975ba44f846d68
+  data.tar.gz: 0e731e759758f27e1d64a721a9e5aa9eb275e76bf7e01e3e4fe027d2baad520c3b3f249a28bd049fb392278e47a3f646322d54488648136fdba389adc4f0b5c0

data/context/documentation-guidelines.md

@@ -16,7 +16,7 @@ Source code documentation is included adjacent to the code it describes, using s
 However, in short:
 
 - Documentation is expected to be in markdown format.
-- You may embed links to definitions using `{MyClass}` or `{my_method}`.
+- You may embed links to definitions using ruby:`MyClass` or ruby:`my_method`.
 - You can use tags:
   - `@parameters name [Type] Description.`
   - `@yields {|argument| ...} If a block is given.`
@@ -173,7 +173,7 @@ $ bundle add $project
 
 `$project` has several core concepts:
 
-- A {ruby MyProject::MyClass} which represents the main entry point for using the project.
+- A ruby:`MyProject::MyClass` which represents the main entry point for using the project.
 
 ## Usage
 
@@ -284,7 +284,7 @@ Following `utopia-project` guidelines, each guide should:
 2. **Provide user context**: Explain why users would need this feature
 3. **Include practical examples**: Working code samples that demonstrate real scenarios
 4. **Follow consistent structure**: Problem → Use Cases → Implementation → Best Practices
-5. **Cross-reference appropriately**: Use `{ruby ClassName}` for internal references
+5. **Cross-reference appropriately**: Use ruby:`ClassName` for internal references
 6. **Include error handling**: Show how to handle common failure scenarios
 7. **Provide troubleshooting**: Common issues and solutions
 8. **Maintain currency**: Keep examples updated with latest best practices

data/context/index.yaml

@@ -3,9 +3,11 @@
 ---
 description: A project documentation tool based on Utopia.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/utopia-project/issues
+  changelog_uri: https://github.com/socketry/utopia-project/blob/main/releases.md
   documentation_uri: https://socketry.github.io/utopia-project/
   funding_uri: https://github.com/sponsors/ioquatix/
-  source_code_uri: https://github.com/socketry/utopia-project/
+  source_code_uri: https://github.com/socketry/utopia-project.git
 files:
 - path: getting-started.md
   title: Getting Started

data/lib/utopia/project/base.md

@@ -4,4 +4,4 @@ Provides structured access to a project directory which contains source code and
 
 ## Usage
 
-To get an instance for the current project, use {Base#instance}.
+To get an instance for the current project, use ruby:`Base#instance`.

data/lib/utopia/project/base.rb

@@ -136,12 +136,12 @@ module Utopia
 			end
 			
 			# Format the given text in the context of the given definition and language.
-			# See {document} for details.
+			# See ruby:`document` for details.
 			# @returns [XRB::MarkupString]
 			#
 			# @example Format text with code links
 			# 	base = Utopia::Project::Base.new
-			# 	base.format("See {Utopia::Project::Base#guides}.") # => XRB::MarkupString
+			# 	base.format("See ruby:`Utopia::Project::Base#guides`.") # => XRB::MarkupString
 			def format(text, definition = nil, language: definition&.language, **options)
 				if document = self.document(text, definition, language: language)
 					return XRB::Markup.raw(
@@ -152,7 +152,7 @@ module Utopia
 			
 			# Convert the given markdown text into HTML.
 			#
-			# Updates source code references (`{language identifier}`) into links.
+			# Updates language-prefixed inline code (e.g. `ruby:` followed by inline code) into links.
 			#
 			# @returns [Document]
 			#

data/lib/utopia/project/document.rb

@@ -29,7 +29,7 @@ module Utopia
 			# Parse and resolve the document root.
 			# @returns [Markly::Node] The root document node.
 			def root
-				@root ||= resolve(Markly.parse(@text, extensions: [:table]))
+				@root ||= resolve(Markly.parse(@text, flags: Markly::INLINE_CODE_INFO, extensions: [:table]))
 			end
 			
 			# Extract the leading heading as the document title.
@@ -99,7 +99,12 @@ module Utopia
 			# @parameter node [Markly::Node] The node to render.
 			# @returns [XRB::MarkupString] The rendered HTML markup.
 			def to_html(node = self.root, **options)
-				renderer = Renderer.new(ids: true, flags: Markly::UNSAFE, **options)
+				renderer = Renderer.new(
+					inline_code_resolver: (@index ? method(:reference_node) : nil),
+					ids: true,
+					flags: Markly::UNSAFE,
+					**options
+				)
 				XRB::Markup.raw(renderer.render(node))
 			end
 			
@@ -160,15 +165,9 @@ module Utopia
 			# @parameter language [String | Nil] The source language name.
 			# @returns [Markly::Node] The code node.
 			def code_node(content, language = nil)
-				if language
-					node = inline_html_node(
-						"<code class=\"language-#{language}\">#{XRB::Strings.to_html(content)}</code>"
-					)
-				else
-					node = Markly::Node.new(:code)
-					node.string_content = content
-					return node
-				end
+				node = Markly::Node.new(:code)
+				node.string_content = content
+				node.code_info = language if language
 				
 				return node
 			end
@@ -176,9 +175,17 @@ module Utopia
 			private
 			
 			# Replace source code references in the given text with HTML anchors.
-			#
-			def reference_node(content)
-				if reference = @index.languages.parse_reference(content, default_language: @default_language)
+			# @parameter content [String] The source code reference.
+			# @parameter language [String | Nil] The explicit source language.
+			# @returns [Markly::Node] The resolved link or code node.
+			def reference_node(content, language: nil)
+				reference = if language
+					@index.languages.reference_for(language, content)
+				else
+					@index.languages.parse_reference(content, default_language: @default_language)
+				end
+				
+				if reference
 					definition = @index.lookup(reference, relative_to: @definition)
 				end
 				
@@ -189,7 +196,7 @@ module Utopia
 				elsif reference
 					code_node(reference.identifier, reference.language.name)
 				else
-					code_node(content)
+					code_node(content, language)
 				end
 			end
 			

data/lib/utopia/project/inheritance.rb

@@ -13,8 +13,8 @@ module Utopia
 			# A method inherited from another definition.
 			Method = Struct.new(:name, :definition)
 			
-			# A group of inherited methods with the same origin.
-			Group = Struct.new(:definition, :methods)
+			# Methods inherited through a direct relationship.
+			Group = Struct.new(:kind, :definition, :methods)
 			
 			# Initialize inheritance resolution for the given definition.
 			# @parameter index [Decode::Index] The index used to resolve relationships.
@@ -55,10 +55,10 @@ module Utopia
 			end
 			
 			# Enumerate documented public and protected methods inherited by the definition.
-			# @returns [Array(Group)] Methods grouped by the definition which provides them.
+			# @returns [Array(Group)] Methods grouped by the direct relationship which provides them.
 			def inherited_methods
 				@groups = []
-				@groups_by_definition = {}
+				@groups_by_relationship = {}
 				
 				collect_instance_methods(@definition, false, {}, {})
 				collect_class_methods(@definition, false, {}, {})
@@ -113,46 +113,46 @@ module Utopia
 				end
 			end
 			
-			def collect_instance_methods(definition, include_own, seen, visited, display_prefix = "#")
+			def collect_instance_methods(definition, include_own, seen, visited, display_prefix: "#", kind: nil, provider: nil)
 				key = [definition.qualified_name, display_prefix]
 				return if visited[key]
 				visited[key] = true
 				
 				relationship_definitions(definition, :prepends).reverse_each do |relationship|
-					collect_instance_methods(relationship, true, seen, visited, display_prefix)
+					collect_instance_methods(relationship, true, seen, visited, display_prefix: display_prefix, kind: kind || :prepend, provider: provider || relationship)
 				end
 				
-				collect_methods(definition, "#", display_prefix, include_own, seen)
+				collect_methods(definition, "#", display_prefix, include_own, seen, kind: kind, provider: provider)
 				
 				relationship_definitions(definition, :includes).reverse_each do |relationship|
-					collect_instance_methods(relationship, true, seen, visited, display_prefix)
+					collect_instance_methods(relationship, true, seen, visited, display_prefix: display_prefix, kind: kind || :include, provider: provider || relationship)
 				end
 				
 				if display_prefix == "#" && (super_class = super_class_for(definition))
-					collect_instance_methods(super_class, true, seen, visited, display_prefix)
+					collect_instance_methods(super_class, true, seen, visited, display_prefix: display_prefix, kind: kind || :super_class, provider: provider || super_class)
 				end
 			end
 			
-			def collect_class_methods(definition, include_own, seen, visited)
+			def collect_class_methods(definition, include_own, seen, visited, kind: nil, provider: nil)
 				key = definition.qualified_name
 				return if visited[key]
 				visited[key] = true
 				
-				collect_methods(definition, ".", ".", include_own, seen)
+				collect_methods(definition, ".", ".", include_own, seen, kind: kind, provider: provider)
 				if singleton = singleton_for(definition)
-					collect_methods(singleton, "#", ".", include_own, seen, definition)
+					collect_methods(singleton, "#", ".", include_own, seen, kind: kind, provider: provider)
 				end
 				
 				relationship_definitions(definition, :extends).reverse_each do |relationship|
-					collect_instance_methods(relationship, true, seen, {}, ".")
+					collect_instance_methods(relationship, true, seen, {}, display_prefix: ".", kind: kind || :extend, provider: provider || relationship)
 				end
 				
 				if super_class = super_class_for(definition)
-					collect_class_methods(super_class, true, seen, visited)
+					collect_class_methods(super_class, true, seen, visited, kind: kind || :super_class, provider: provider || super_class)
 				end
 			end
 			
-			def collect_methods(definition, source_prefix, display_prefix, include_own, seen, origin = definition)
+			def collect_methods(definition, source_prefix, display_prefix, include_own, seen, kind:, provider:)
 				methods_for(definition, source_prefix).each do |method|
 					name = "#{display_prefix}#{method.name}"
 					next if seen[name]
@@ -168,13 +168,14 @@ module Utopia
 					next unless method.documented?
 					next if method.respond_to?(:private?) && method.private?
 					
-					add_method(origin, name, method)
+					add_method(kind, provider, name, method)
 				end
 			end
 			
-			def add_method(definition, name, method)
-				group = @groups_by_definition[definition.qualified_name] ||= begin
-					group = Group.new(definition, [])
+			def add_method(kind, provider, name, method)
+				key = [kind, provider.qualified_name]
+				group = @groups_by_relationship[key] ||= begin
+					group = Group.new(kind, provider, [])
 					@groups << group
 					group
 				end

data/lib/utopia/project/renderer.rb

@@ -10,6 +10,15 @@ module Utopia
 	module Project
 		# Renders project Markdown with support for Mermaid code blocks.
 		class Renderer < Markly::Renderer::HTML
+			# Initialize the project renderer.
+			# @parameter inline_code_resolver [Proc | Nil] Resolves language-prefixed inline code into a replacement node.
+			def initialize(inline_code_resolver: nil, **options)
+				@inline_code_resolver = inline_code_resolver
+				@resolving_inline_code = false
+				
+				super(**options)
+			end
+			
 			# Render a heading and expose its title to Pagefind for sub-results.
 			# @parameter node [Markly::Node] The heading node.
 			def header(node)
@@ -45,6 +54,21 @@ module Utopia
 					super
 				end
 			end
+			
+			# Render inline code, resolving language-prefixed references when possible.
+			# @parameter node [Markly::Node] The inline code node.
+			def code(node)
+				if @inline_code_resolver && !@resolving_inline_code && (language = node.code_language)
+					begin
+						@resolving_inline_code = true
+						out(@inline_code_resolver.call(node.string_content, language: language))
+					ensure
+						@resolving_inline_code = false
+					end
+				else
+					super
+				end
+			end
 		end
 	end
 end

data/lib/utopia/project/version.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 module Utopia
 	module Project
-		VERSION = "0.42.0"
+		VERSION = "0.44.0"
 	end
 end

data/pages/_header.xnode

@@ -12,7 +12,7 @@
 				?><a href="#{link.href}" class="#{active ? 'active' : nil}" aria-current="#{active ? 'page' : 'false'}">#{link.title}</a><?r
 			end ?>
 			<?r if github_url = base.source_code_uri ?>
-				<a href="#{github_url}" class="github" target="_blank" rel="noopener noreferrer" aria-label="View source on GitHub">GitHub <span aria-hidden="true">↗</span></a>
+				<a href="#{github_url}" class="github" target="_blank" rel="noopener noreferrer" aria-label="View source on GitHub">GitHub</a>
 			<?r end ?>
 		</div>
 		<div class="header-actions">

data/pages/reference/_declaration.xnode

@@ -2,8 +2,9 @@
 base = self[:base]
 symbol = self[:symbol]
 link = self[:link]
+inheritance = self[:inheritance] != false
 
-if symbol.respond_to?(:super_class)
+if inheritance && symbol.respond_to?(:super_class)
 	super_class = symbol.super_class
 end
 

data/pages/reference/_relationships.xnode

@@ -5,6 +5,9 @@ inheritance = base.inheritance_for(symbol)
 
 relationships = inheritance.relationships
 inherited_methods = inheritance.inherited_methods
+inherited_methods_by_relationship = inherited_methods.to_h do |group|
+	[[group.kind, group.definition.qualified_name], group.methods]
+end
 
 relationship_labels = {
 	super_class: "Inherits from",
@@ -14,32 +17,35 @@ relationship_labels = {
 }
 ?>
 <?r if relationships.any? ?>
-	<dl class="relationships"><?r
+	<dl class="relationships" data-pagefind-ignore><?r
 		relationships.group_by(&:kind).each do |kind, entries|
 			?><dt>#{relationship_labels.fetch(kind)}</dt>
 			<dd><?r
 				entries.each_with_index do |relationship, index|
 					if index > 0
-						?>, <?r
+						?>; <?r
 					end
 					
 					?>#{base.linkify(relationship.name, symbol)}<?r
+					
+					methods = if relationship.definition
+						key = [kind, relationship.definition.qualified_name]
+						inherited_methods_by_relationship[key]
+					end
+					
+					if methods&.any?
+						?><code>: <?r
+						methods.each_with_index do |method, method_index|
+							if method_index > 0
+								?>, <?r
+							end
+							
+							?><a href="#{base.link_for(method.definition)}">#{method.name}</a><?r
+						end
+						?></code><?r
+					end
 				end
 			?></dd><?r
 		end
 	?></dl>
 <?r end ?>
-
-<?r if inherited_methods.any? ?>
-	<section>
-		<h2>Inherited Methods</h2><?r
-		inherited_methods.each do |group|
-			?><p>From <a href="#{base.link_for(group.definition)}"><code>#{group.definition.qualified_name}</code></a>:</p>
-			<ul class="index"><?r
-				group.methods.each do |method|
-					?><li><a href="#{base.link_for(method.definition)}"><code>#{method.name}</code></a></li><?r
-				end
-			?></ul><?r
-		end
-	?></section>
-<?r end ?>

data/pages/reference/controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 prepend Actions
 

data/pages/reference/show.xnode

@@ -30,7 +30,7 @@
 	if nested.any?
 	?>
 	<section>
-		<h2>Classes and Modules</h2>
+		<h2>Nested Classes and Modules</h2>
 		
 		<dl class="nested-definitions">
 			<?r nested.each do |symbol|
@@ -40,7 +40,7 @@
 				end
 			?>
 			<div>
-				<dt>#{partial 'content:declaration', symbol: symbol, link: true}</dt>
+				<dt>#{partial 'content:declaration', symbol: symbol, link: true, inheritance: false}</dt>
 				<dd><?r unless description&.empty? ?>#{base.format(description, symbol)}<?r end ?></dd>
 			</div>
 			<?r end ?>

data/public/_static/site.css

@@ -170,10 +170,6 @@ header .sections .github {
 	opacity: 0.7;
 }
 
-header .sections .github span {
-	font-size: 0.85em;
-}
-
 header .sections .github:hover {
 	opacity: 1;
 }

data/readme.md

@@ -33,6 +33,10 @@ Please see the [project documentation](https://socketry.github.io/utopia-project
 
 Please see the [project releases](https://socketry.github.io/utopia-project/releases/index) for all releases.
 
+### v0.44.0
+
+  - Add support for language-prefixed inline code references such as ruby:`Object.new`.
+
 ### v0.41.0
 
   - Don't render empty signature block when there are only examples.
@@ -72,10 +76,6 @@ Please see the [project releases](https://socketry.github.io/utopia-project/rele
 
   - Fix presentation of release notes on releases page.
 
-### v0.31.0
-
-  - Support brief release notes in `releases.md` document.
-
 ## See Also
 
   - [Utopia](https://github.com/socketry/utopia) — The website framework which powers this web application.

data/releases.md

@@ -1,5 +1,9 @@
 # Changes
 
+## v0.44.0
+
+  - Add support for language-prefixed inline code references such as ruby:`Object.new`.
+
 ## v0.41.0
 
   - Don't render empty signature block when there are only examples.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.42.0
+  version: 0.44.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -75,14 +75,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.17'
 - !ruby/object:Gem::Dependency
   name: thread-local
   requirement: !ruby/object:Gem::Requirement
@@ -378,13 +378,15 @@ files:
 - template/config/serve.rb
 - template/gems.rb
 - template/preload.rb
-homepage: https://socketry.github.io/utopia-project
+homepage: https://github.com/socketry/utopia-project
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/utopia-project/issues
+  changelog_uri: https://github.com/socketry/utopia-project/blob/main/releases.md
   documentation_uri: https://socketry.github.io/utopia-project/
   funding_uri: https://github.com/sponsors/ioquatix/
-  source_code_uri: https://github.com/socketry/utopia-project/
+  source_code_uri: https://github.com/socketry/utopia-project.git
 rdoc_options: []
 require_paths:
 - lib