utopia-project 0.33.2 → 0.34.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b026a55470cb43f0e15336c742d109cdc868d3f60c98b4628d6bfe39b14ed156
-  data.tar.gz: 723621437bf6b318120fe1a8260482f3eb1a6809a199af50c9571bc224df1729
+  metadata.gz: f6d7813076feeeb716ee8b2fed2db46d2d5522d63ef443632687aec95be009f9
+  data.tar.gz: a77ff26f76a698e3d9c90b86270a4ee9fefeecd6108e9bade9c5d603ffe38081
 SHA512:
-  metadata.gz: b2b39d0c3dd6927baf8d106723b949d870f772b91d67494d2ee23bf077c06f93477bbf94fc7ff7c1669d25dc227f3d4f9a22e6a099dc495f15b96b19defc9908
-  data.tar.gz: ceff9c6369bd465f9a4da7120be81e3c2b81a3f58cb01181e1823e6c07cffcee8cd21f329387d0510b6613a89af84de1f57aab6cebb310892c78488dc9e5a8b4
+  metadata.gz: 33e47b9495910bd0e04b7b3f35f05f06de0e02c827dcb2c08cc8619b81b70e9986b288f4014a3c5fa544b38c97a21e3373287f49881ad67cedd868353b4e91cf
+  data.tar.gz: aad59c90eb1f6556f6332f42afab40bc81031f2414df7fe83231a9bdb71fe2de7f6a4491aec52b53ab225049732c3d7cd0f92722ae4813331bebc29385c2be3c

data/bake/utopia/project/agent/context.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+def initialize(...)
+	super
+	
+	require "utopia/project"
+end
+
+# Update agent context files from the guides.
+def update
+	project = Utopia::Project::Base.new(context.root)
+	
+	FileUtils.mkdir_p self.context_root
+	files = []
+	
+	# Sort guides by order, then by name
+	sorted_guides = project.guides.select(&:readme?).sort
+	
+	sorted_guides.each do |guide|
+		FileUtils.cp guide.readme_path, self.context_path_for(guide)
+		files << {
+			"path" => guide.name + ".md",
+			"title" => guide.title,
+			"description" => guide.description.to_markdown.chomp,
+		}
+	end
+	
+	if files.any?
+		# Create index in agent-context compatible format
+		gemspec = project.gemspec
+		index = {
+			"description" => gemspec&.summary,
+			"metadata" => gemspec&.metadata || {},
+			"files" => files,
+		}
+		
+		File.open(self.context_index_path, "w") do |file|
+			file.puts "# Automatically generated context index for Utopia::Project guides."
+			file.puts "# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`."
+			YAML.dump(index, file)
+		end
+		
+		return index
+	end
+	
+	return nil
+end
+
+private
+
+def context_root
+	File.join(context.root, "context")
+end
+
+def context_path_for(guide)
+	File.join(context_root, guide.name + ".md")
+end
+
+def context_index_path
+	File.join(context_root, "index.yaml")
+end

data/bake/utopia/project/readme/update.rb

@@ -3,14 +3,17 @@
 # Released under the MIT License.
 # Copyright, 2023-2025, by Samuel Williams.
 
-require "utopia/project"
-require "xrb"
+def initialize(...)
+	super
+	
+	require "utopia/project"
+end
 
 def update(path: "readme.md", documentation_url: nil)
 	project = Utopia::Project::Base.new(context.root)
 	readme = project.readme_document
 	
-	documentation_url ||= public_documentation_url
+	documentation_url ||= public_documentation_url(project)
 	
 	readme.replace_section("Usage") do |header|
 		current = header
@@ -39,25 +42,15 @@ private
 
 Scope = Struct.new(:documentation_url, :project)
 
-def gemspec_path
-	Dir.glob("*.gemspec", base: context.root).first
-end
-
-def gemspec
-	if gemspec_path = self.gemspec_path
-		@gemspec ||= ::Gem::Specification.load(gemspec_path)
-	end
-end
-
 # The public documentation URL if it can be determined.
-def public_documentation_url
-	if metadata = gemspec.metadata
+def public_documentation_url(project)
+	if metadata = project.gemspec&.metadata
 		if documentation_uri = metadata["documentation_uri"]
 			return documentation_uri
 		end
 	end
 	
-	return gemspec&.homepage
+	return project.gemspec&.homepage
 end
 
 def usage_section(documentation_url, project)
@@ -83,7 +76,7 @@ def releases_section(documentation_url, project)
 	buffer = String.new
 	
 	buffer << "Please see the [project releases](#{documentation_url}releases/index) for all releases.\n"
-
+	
 	project.releases.first(10).each do |release|
 		buffer << "\n### #{release.name}\n\n"
 		

data/bake/utopia/project.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 # Create an empty project in the current directory.
 def create

data/context/documentation-formatting.md

@@ -0,0 +1,67 @@
+# Documentation Formatting
+
+This guide explains the conventions used by `utopia-project` when generating documentation for your project.
+
+## Source Code Documentation
+
+Source code documentation is expected to be in markdown format. This is different from the canonical `RDoc` format used by Ruby. However, using markdown is a good format for standardised documentation across a range of different languages.
+
+### Tags
+
+#### `@parameter`
+
+The `@parameter` tag is used to describe the parameters of a method:
+
+~~~ ruby
+# @parameter x [Integer] The x co-ordinate.
+# @parameter y [Integer] The y co-ordinate.
+def move(x, y)
+	# ...
+end
+~~~
+
+#### `@returns`
+
+The `@returns` tag is used to describe the return type of the definition:
+
+~~~ ruby
+# @returns [Integer] The result of the computation.
+def fib(n)
+	# ...
+end
+~~~
+
+### References
+
+It is possible to insert references in your documentation using curly brackets. In the following example `{Input}` will be expanded relative to the usage, to some symbol named `Input`.
+
+~~~ ruby
+# Frobulates the input, see {Input} for more details.
+def frobulate(input)
+	# ... left to the imagination ...
+end
+~~~
+
+## Examples & Guides
+
+Examples provide structured information to help users understand your project and are located in the `examples/` directory. One sub-directory per example.
+
+### `readme.md`
+
+If an example has a `readme.md` file, it is used as the main source of documentation.
+
+### Source Files
+
+All other source files are listed on the example page. Top level comments with trailing code (segments) are used to help guide the user through the example.
+
+## Diagrams
+
+You can add diagrams formatted using `mermaid.js`.
+
+``` mermaid
+	graph LR;
+			A-->B;
+			A-->C;
+			B-->D;
+			C-->D;
+```

data/context/getting-started.md

@@ -0,0 +1,31 @@
+# Getting Started
+
+This guide explains how to use `utopia-project` for your own project.
+
+## Installation
+
+Firstly, add the gem to your project:
+
+~~~ bash
+$ bundle add utopia-project
+~~~
+
+## Start Local Server
+
+Start the local server to preview documentation:
+
+~~~ bash
+$ bake utopia:project:serve
+~~~
+
+Right now, this server does not reload the code index, so you will need to restart the server to update the code index. This will be fixed in the future.
+
+## Generate Static Site
+
+You can generate a static copy of your documentation into the `docs/` folder:
+
+~~~ bash
+$ bake utopia:project:static
+~~~
+
+You can check the [guide for GitHub Pages](../github-pages-integration/index) which gives more details on how to deploy the static site using GitHub.

data/context/github-pages-integration.md

@@ -0,0 +1,17 @@
+# GitHub Pages Integration
+
+This guide shows you how to use `utopia-project` with GitHub Pages.
+
+## Static Site Generation
+
+Once you are happy with your project's documentation, use this command to generate a static site:
+
+~~~ bash
+$ bake utopia:project:static
+~~~
+
+This will generate a static copy of your documentation into `docs/` which is what is required by GitHub Pages.
+
+## Enable GitHub Pages
+
+In your GitHub project settings, you will need to [enable GitHub Pages served from `docs/`](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source).

data/context/index.yaml

@@ -0,0 +1,19 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A project documentation tool based on Utopia.
+metadata:
+  documentation_uri: https://socketry.github.io/utopia-project/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/utopia-project/
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `utopia-project` for your own project.
+- path: documentation-formatting.md
+  title: Documentation Formatting
+  description: This guide explains the conventions used by `utopia-project` when generating
+    documentation for your project.
+- path: github-pages-integration.md
+  title: GitHub Pages Integration
+  description: This guide shows you how to use `utopia-project` with GitHub Pages.

data/lib/utopia/project/base.rb

@@ -178,7 +178,7 @@ module Utopia
 					
 					next unless File.directory?(guide_path)
 					
-					yield Guide.new(self, guide_path)
+					yield Guide.new(self, guide_path, link.info)
 				end
 			end
 			
@@ -203,6 +203,20 @@ module Utopia
 					releases_document.releases
 				end
 			end
+			
+			# Get the path to the gemspec file for this project.
+			# @returns [String | nil] The relative path to the gemspec file, or nil if not found.
+			private def gemspec_path
+				Dir.glob("*.gemspec", base: @root).first
+			end
+			
+			# Load and return the gemspec for this project.
+			# @returns [Gem::Specification | nil] The loaded gemspec, or nil if not found.
+			def gemspec
+				if gemspec_path = self.gemspec_path
+					@gemspec ||= ::Gem::Specification.load(File.join(@root, gemspec_path))
+				end
+			end
 		end
 	end
 end

data/lib/utopia/project/guide.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require "utopia/path"
 require "xrb/reference"
@@ -14,9 +14,10 @@ module Utopia
 			# Initialize the example with the given root path.
 			# @parameter base [Base] The base instance for the project.
 			# @parameter root [String] The file-system path to the root of the example.
-			def initialize(base, root)
+			def initialize(base, root, metadata)
 				@base = base
 				@root = root
+				@metadata = metadata
 				
 				@documentation = nil
 				
@@ -31,6 +32,39 @@ module Utopia
 			# @attribute [String | Nil]
 			attr :description
 			
+			# The metadata associated with the guide.
+			# @attribute [Hash]
+			attr :metadata
+			
+			def order
+				metadata[:order]
+			end
+			
+			def <=> other
+				if order = self.order
+					if other_order = other.order
+						if order < other_order
+							return -1
+						elsif order > other_order
+							return 1
+						end
+					else
+						# If we have order, but the other doesn't, we come first:
+						return -1
+					end
+				end
+				
+				if name = self.name
+					if other_name = other.name
+						return name <=> other_name
+					else
+						return -1
+					end
+				end
+				
+				return 0
+			end
+			
 			README = "readme.md"
 			
 			# The path to the README file for the guide.

data/lib/utopia/project/linkify.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require "decode/syntax/rewriter"
 

data/lib/utopia/project/releases_document.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "document"
 

data/lib/utopia/project/renderer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "markly"
 require "markly/renderer/html"

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.33.2"
+		VERSION = "0.34.1"
 	end
 end

data/lib/utopia/project.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require "utopia/project/version"
 

data/pages/controller.rb

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

data/pages/guides/controller.rb

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

data/pages/releases/controller.rb

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

data/pages/source/controller.rb

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

data/readme.md

@@ -31,6 +31,14 @@ 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.34.1
+
+  - Fix schema for `index.yaml` context file.
+
+### v0.34.0
+
+  - Introduce `bake utopia:project:agent:context:update` command to update the agent context from the guides in the project.
+
 ### v0.33.2
 
   - Fixed handling of segmented code guides when rendered into a `readme.md` file.

data/releases.md

@@ -1,5 +1,13 @@
 # Changes
 
+## v0.34.1
+
+  - Fix schema for `index.yaml` context file.
+
+## v0.34.0
+
+  - Introduce `bake utopia:project:agent:context:update` command to update the agent context from the guides in the project.
+
 ## v0.33.2
 
   - Fixed handling of segmented code guides when rendered into a `readme.md` file.

data/template/gems.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2020-2025, by Samuel Williams.
+
 source "https://rubygems.org"
 
 group :preload do

data/template/preload.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require "utopia/project"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.33.2
+  version: 0.34.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -130,7 +130,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bake/utopia/project.rb
+- bake/utopia/project/agent/context.rb
 - bake/utopia/project/readme/update.rb
+- context/documentation-formatting.md
+- context/getting-started.md
+- context/github-pages-integration.md
+- context/index.yaml
 - lib/utopia/project.rb
 - lib/utopia/project/base.md
 - lib/utopia/project/base.rb
@@ -278,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A project documentation tool based on Utopia.
 test_files: []