utopia-project 0.33.1 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 243e6190a11eda87e544917c3bdd9eac032751d59cbf6774c4d9306674fa2b77
-  data.tar.gz: d46a3f7228757feeb5e093bcfc5f257a11d2c73607b1488cc604a2d2f2ffe45a
+  metadata.gz: 8e9f2b003ff67529bbe43f3597901c567860a9aee869d108e140f142a948ec6c
+  data.tar.gz: b0103f4c18319d9d48b4d7889a6bc921dc6fa0ce3c48de8b2f44bc545bbc2b75
 SHA512:
-  metadata.gz: b47e681830588383eb8ac12c7da593859835cb6141acbc413d73915102dc919d9294c033c92ea4e986d3258e0594984a14afbec40cb142f63e630a08c6493874
-  data.tar.gz: 16e76eaa43ef6edf0a18dbb7e1e4ca52b2fd6cb1ae806df8bdd8c451225e7c56773d1ed308eb82ed865c139f0ec20a4bfc583be7886067b62c076368f679214e
+  metadata.gz: 98a0b74ebcdadafc34b6cecca41b456a91d63d710db9b1cef039c825f806c408abc79182dc359cfdb28a55ca4d5afeabae2cab12708d2946f44347b4ce8f9f1d
+  data.tar.gz: e95d1f143923f738312910efc6849a488cb7c8a20bae952d770d8b6bc704822af4b7b9b2c7c8e934213a5914e58f9655ea3147591fdb790558209d67753eece9

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

@@ -0,0 +1,53 @@
+# 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
+	index = {}
+	
+	project.guides.each do |guide|
+		if guide.readme?
+			FileUtils.cp guide.readme_path, self.context_path_for(guide)
+			index[guide.name] = {
+				"title" => guide.title,
+				"order" => guide.order,
+				"description" => guide.description.to_markdown.chomp,
+			}
+		end
+	end
+	
+	if index.any?
+		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
+	end
+	
+	return index
+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

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# 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)
@@ -52,7 +55,7 @@ end
 # The public documentation URL if it can be determined.
 def public_documentation_url
 	if metadata = gemspec.metadata
-		if documentation_uri = metadata['documentation_uri']
+		if documentation_uri = metadata["documentation_uri"]
 			return documentation_uri
 		end
 	end
@@ -66,7 +69,14 @@ def usage_section(documentation_url, project)
 	buffer << "Please see the [project documentation](#{documentation_url}) for more details.\n"
 	
 	project.guides.each do |guide|
-		buffer << "  - [#{guide.title}](#{guide.href(documentation_url)}) - #{guide.description.to_markdown}\n"
+		if description = guide.description
+			buffer << "  - [#{guide.title}](#{guide.href(documentation_url)}) - #{description.to_markdown}\n"
+		elsif documentation = guide.documentation
+			document = project.document(documentation.text, language: guide.documentation.language)
+			buffer << "  - [#{guide.title}](#{guide.href(documentation_url)}) - #{document.to_markdown}\n"
+		else
+			buffer << "  - [#{guide.title}](#{guide.href(documentation_url)})\n"
+		end
 	end
 	
 	return Markly.parse(buffer)
@@ -76,7 +86,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-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 # Create an empty project in the current directory.
 def create
@@ -38,7 +38,7 @@ end
 # @parameter output_path [String] The output path for the static site.
 # @parameter force [Boolean] Remove the output directory before generating the static content.
 def static(output_path: "docs", force: true)
-	require 'rackula/command'
+	require "rackula/command"
 	
 	config_path = File.expand_path("../../template/config.ru", __dir__)
 	public_path = File.expand_path("../../public", __dir__)
@@ -60,7 +60,7 @@ end
 
 # Extract a description for the project.
 def description(root: context.root)
-	require 'markly'
+	require "markly"
 	
 	readme_path = File.join(root, "readme.md")
 	if File.exist?(readme_path)

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,16 @@
+# 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`.
+---
+getting-started:
+  title: Getting Started
+  order: 1
+  description: This guide explains how to use `utopia-project` for your own project.
+documentation-formatting:
+  title: Documentation Formatting
+  order: 2
+  description: This guide explains the conventions used by `utopia-project` when generating
+    documentation for your project.
+github-pages-integration:
+  title: GitHub Pages Integration
+  order: 3
+  description: This guide shows you how to use `utopia-project` with GitHub Pages.

data/lib/utopia/project/base.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2023, by Michael Adams.
 
-require 'utopia/path'
-require 'utopia/content/links'
+require "utopia/path"
+require "utopia/content/links"
 
-require 'xrb/reference'
-require 'decode'
+require "xrb/reference"
+require "decode"
 
-require 'thread/local'
+require "thread/local"
 
-require_relative 'document'
-require_relative 'releases_document'
+require_relative "document"
+require_relative "releases_document"
 
-require_relative 'guide'
-require_relative 'linkify'
+require_relative "guide"
+require_relative "linkify"
 
 module Utopia
 	module Project
@@ -120,13 +120,6 @@ module Utopia
 			# See {document} for details.
 			# @returns [XRB::MarkupString]
 			def format(text, definition = nil, language: definition&.language, **options)
-				case text
-				when Enumerable
-					text = text.to_a.join("\n")
-				when nil
-					return nil
-				end
-				
 				if document = self.document(text, definition, language: language)
 					return XRB::Markup.raw(
 						document.to_html(**options)
@@ -140,6 +133,13 @@ module Utopia
 			#
 			# @returns [Document]
 			def document(text, definition = nil, language: definition&.language)
+				case text
+				when Enumerable
+					text = text.to_a.join("\n")
+				when nil
+					return nil
+				end
+				
 				Document.new(text, self, definition: definition, default_language: language)
 			end
 			
@@ -178,12 +178,12 @@ module Utopia
 					
 					next unless File.directory?(guide_path)
 					
-					yield Guide.new(self, guide_path)
+					yield Guide.new(self, guide_path, link.info)
 				end
 			end
 			
 			def readme_document
-				if path = self.path_for('readme.md') || self.path_for('README.md')
+				if path = self.path_for("readme.md") || self.path_for("README.md")
 					Document.new(File.read(path), self)
 				end
 			end
@@ -193,7 +193,7 @@ module Utopia
 			end
 			
 			def releases_document
-				if path = self.path_for('releases.md')
+				if path = self.path_for("releases.md")
 					ReleasesDocument.new(File.read(path), self)
 				end
 			end

data/lib/utopia/project/document.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require_relative 'renderer'
-require 'xrb'
+require_relative "renderer"
+require "xrb"
 
 module Utopia
 	module Project
@@ -72,6 +72,10 @@ module Utopia
 				end
 			end
 			
+			def to_markdown(**options)
+				self.root.to_markdown(**options)
+			end
+			
 			def to_html(node = self.root, **options)
 				renderer = Renderer.new(ids: true, flags: Markly::UNSAFE, **options)
 				XRB::Markup.raw(renderer.render(node))

data/lib/utopia/project/guide.rb

@@ -1,11 +1,11 @@
 # 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'
-require 'decode'
+require "utopia/path"
+require "xrb/reference"
+require "decode"
 
 module Utopia
 	module Project
@@ -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,14 @@ module Utopia
 			# @attribute [String | Nil]
 			attr :description
 			
+			# The metadata associated with the guide.
+			# @attribute [Hash]
+			attr :metadata
+			
+			def order
+				metadata[:order]
+			end
+			
 			README = "readme.md"
 			
 			# The path to the README file for the guide.

data/lib/utopia/project/linkify.rb

@@ -1,9 +1,9 @@
 # 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'
+require "decode/syntax/rewriter"
 
 module Utopia
 	module Project
@@ -24,14 +24,14 @@ module Utopia
 			
 			def link_to(definition, text)
 				XRB::Builder.fragment do |builder|
-					builder.inline('a', href: @base.link_for(definition), title: definition.qualified_name) do
+					builder.inline("a", href: @base.link_for(definition), title: definition.qualified_name) do
 						builder.text(text)
 					end
 				end
 			end
 			
 			def apply(output = XRB::Builder.new)
-				output.inline('code', class: "language-#{@language.name}") do
+				output.inline("code", class: "language-#{@language.name}") do
 					super
 				end
 				

data/lib/utopia/project/releases_document.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require_relative 'document'
+require_relative "document"
 
 module Utopia
 	module Project

data/lib/utopia/project/renderer.rb

@@ -1,10 +1,10 @@
 # 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'
+require "markly"
+require "markly/renderer/html"
 
 module Utopia
 	module Project

data/lib/utopia/project/version.rb

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

data/lib/utopia/project.rb

@@ -1,15 +1,15 @@
 # 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"
 
-require 'variant'
+require "variant"
 
-require 'utopia/localization'
+require "utopia/localization"
 
-require_relative 'project/base'
+require_relative "project/base"
 
 module Utopia
 	module Project
@@ -43,13 +43,13 @@ module Utopia
 			builder.use Utopia::Static, root: PUBLIC_ROOT
 			
 			builder.use Utopia::Redirection::Rewrite, {
-				'/' => '/index'
+				"/" => "/index"
 			}
 			
 			builder.use Utopia::Redirection::DirectoryIndex
 			
 			builder.use Utopia::Redirection::Errors, {
-				404 => '/errors/file-not-found'
+				404 => "/errors/file-not-found"
 			}
 			
 			if locales
@@ -66,7 +66,7 @@ module Utopia
 				# 'gallery' => Utopia::Gallery::Tags.new
 			}
 			
-			builder.run lambda { |env| [404, {}, []] }
+			builder.run lambda {|env| [404, {}, []]}
 		end
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2020-2024, by Samuel Williams.  
+Copyright, 2020-2025, by Samuel Williams.  
 Copyright, 2020, by Olle Jonsson.  
 Copyright, 2022-2023, by dependabot[bot].  
 Copyright, 2023, by Michael Adams.  

data/pages/controller.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 prepend Actions
 
-on '**' do
+on "**" do
 	@base = Utopia::Project::Base.instance
 end
 
-on 'index' do
+on "index" do
 	if @document = @base.readme_document
 		@document.replace_section("Usage") do |header|
 			header.insert_after(@document.html_node("<content:usage/>"))

data/pages/guides/controller.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 prepend Actions
 
-on '**/*/index' do |request, path|
+on "**/*/index" do |request, path|
 	name = path.components[-2]
 	
 	@guide = @base.guides.find do |guide|

data/pages/releases/controller.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 prepend Actions
 
-on 'index' do
+on "index" do
 	@document = @base.releases_document
 end

data/pages/source/controller.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 prepend Actions
 
-on '**/*/index' do |request, path|
+on "**/*/index" do |request, path|
 	@lexical_path = path.components.dup
 	# Remove the last "index" part:
 	@lexical_path.pop

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.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.
+
 ### v0.33.0
 
   - Fix presentation of release notes on releases page.

data/releases.md

@@ -1,6 +1,12 @@
 # Changes
 
-This document outlines major changes and new features in each release of the project.
+## 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.
 
 ## v0.33.0
 

data/template/config.ru

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
 
-require 'utopia/setup'
+require "utopia/setup"
 UTOPIA ||= Utopia.setup(Dir.pwd)
 
-require 'utopia/project'
+require "utopia/project"
 Utopia::Project.call(self)

data/template/gems.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2025, by Samuel Williams.
+
+source "https://rubygems.org"
+
+group :preload do
+	gem "utopia-project"
+end

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'
+require "utopia/project"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.33.1
+  version: 0.34.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -39,7 +39,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: decode
@@ -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
@@ -254,8 +259,8 @@ files:
 - public/robots.txt
 - readme.md
 - releases.md
-- template/Gemfile
 - template/config.ru
+- template/gems.rb
 - template/preload.rb
 homepage: https://socketry.github.io/utopia-project
 licenses:
@@ -271,14 +276,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A project documentation tool based on Utopia.
 test_files: []

data/template/Gemfile

@@ -1,6 +0,0 @@
-
-source "https://rubygems.org"
-
-group :preload do
-	gem "utopia-project"
-end