Add support for @example pragmas.

Author: ioquatix

lib/utopia/project/base.rb

@@ -59,6 +59,10 @@ def initialize(root = Dir.pwd)
 			# Return the absolute path for the given file name, if it exists in the project.
 			# @parameter file_name [String] The relative path to the project file, e.g. `readme.md`.
 			# @returns [String] The file-system path.
+			#
+			# @example Get README path
+			# 	base = Utopia::Project::Base.new
+			# 	base.path_for("readme.md") # => "/path/to/project/readme.md" or nil
 			def path_for(file_name)
 				full_path = File.expand_path(file_name, @root)
 				if File.exist?(full_path)
@@ -86,6 +90,10 @@ def best(definitions)
 
 			# Given a lexical path, find the best definition for that path.
 			# @returns [Tuple(Decode::Trie::Node, Decode::Definition)]
+			#
+			# @example Lookup a definition
+			# 	base = Utopia::Project::Base.local
+			# 	_, definition = base.lookup(%i[Utopia Project Base])
 			def lookup(path)
 				if node = @index.trie.lookup(path.map(&:to_sym))
 					return node, best(node.values)
@@ -119,6 +127,10 @@ def linkify(text, definition, language: definition&.language)
 			# Format the given text in the context of the given definition and language.
 			# See {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
 			def format(text, definition = nil, language: definition&.language, **options)
 				if document = self.document(text, definition, language: language)
 					return XRB::Markup.raw(
@@ -132,6 +144,11 @@ def format(text, definition = nil, language: definition&.language, **options)
 			# Updates source code references (`{language identifier}`) into links.
 			#
 			# @returns [Document]
+			#
+			# @example Convert markdown to HTML
+			# 	base = Utopia::Project::Base.new
+			# 	doc = base.document("# Title")
+			# 	doc.to_html # => "<h1>Title</h1>\n"
 			def document(text, definition = nil, language: definition&.language)
 				case text
 				when Enumerable
@@ -145,6 +162,11 @@ def document(text, definition = nil, language: definition&.language)
 
 			# Compute a unique string which can be used as `id` attribute in the HTML output.
 			# @returns [String]
+			#
+			# @example Compute id for a definition
+			# 	base = Utopia::Project::Base.local
+			# 	_, definition = base.lookup(%i[Utopia Project Base])
+			# 	base.id_for(definition) # => "Utopia::Project::Base"
 			def id_for(definition, suffix = nil)
 				if suffix
 					"#{definition.qualified_name}-#{suffix}"
@@ -155,6 +177,11 @@ def id_for(definition, suffix = nil)
 
 			# Compute a link href to the given definition for use within the HTML output.
 			# @returns [XRB::Reference]
+			#
+			# @example Link to a definition
+			# 	base = Utopia::Project::Base.local
+			# 	_, definition = base.lookup(%i[Utopia Project Base])
+			# 	base.link_for(definition).to_s # => "/source/utopia/project/index#Utopia::Project::Base"
 			def link_for(definition)
 				path = definition.lexical_path.map{|entry| entry.to_s}
 
@@ -170,6 +197,12 @@ def link_for(definition)
 			# @yields {|guide| ...} If a block is given.
 			# 	@parameter guide [Guide]
 			# @returns [Enumerator(Guide)] If no block given.
+			#
+			# @example List guide titles
+			# 	base = Utopia::Project::Base.new
+			# 	base.guides.each do |guide|
+			# 		puts guide.title
+			# 	end
 			def guides
 				return to_enum(:guides) unless block_given?
 

pages/source/_examples.xnode

@@ -0,0 +1,18 @@
+<?r
+base = self[:base]
+
+symbol = attributes[:symbol] 
+documentation = symbol.documentation
+
+examples = documentation&.filter(Decode::Comment::Example).to_a
+
+if examples&.any? ?>
+	<?r examples.each do |example| ?>
+		<details closed>
+			<?r if title = example.title ?>
+				<summary><h4>Example: #{title}</h4></summary>
+			<?r end ?>
+			<pre><code class="language-#{symbol.language.name}">#{example.code}</code></pre>
+		</details>
+	<?r end ?>
+<?r end ?>

pages/source/_signature.xnode

@@ -10,6 +10,8 @@
 	<dl><?r
 		documentation.traverse do |node, descend|
 			node.each do |child|
+				next if child.is_a?(Decode::Comment::Example)
+				
 				?><dt>
 					<strong>#{child.directive}</strong><?r
 						case child

pages/source/show.xnode

@@ -17,6 +17,7 @@
 		?>#{base.format(text.join("\n"), symbol)}<?r
 	end
 	?>
+	#{partial 'content:examples', symbol: symbol}
 	#{partial 'content:signature', symbol: symbol}
 	<?r
 	nested = node.children.map do |name, child|
@@ -56,6 +57,7 @@
 				if documentation = symbol.documentation
 					?>#{partial 'content:pragmas', symbol: symbol}<?r
 					?>#{base.format(documentation.text, symbol)}<?r
+					?>#{partial 'content:examples', symbol: symbol}<?r
 					?>#{partial 'content:signature', symbol: symbol}<?r
 				end
 

releases.md

@@ -1,5 +1,9 @@
 # Changes
 
+## Unreleased
+
+  - Support for `@example` pragmas from the `decode` gem, allowing inline code examples to be rendered in API documentation.
+
 ## v0.37.2
 
   - Fix mermaid diagram text color in dark mode.

utopia-project.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
 
 	spec.required_ruby_version = ">= 3.2"
 
-	spec.add_dependency "decode", "~> 0.17"
+	spec.add_dependency "decode", "~> 0.26"
 	spec.add_dependency "falcon"
 	spec.add_dependency "markly", "~> 0.7"
 	spec.add_dependency "rackula", "~> 1.3"