utopia-project 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e9f2b003ff67529bbe43f3597901c567860a9aee869d108e140f142a948ec6c
-  data.tar.gz: b0103f4c18319d9d48b4d7889a6bc921dc6fa0ce3c48de8b2f44bc545bbc2b75
+  metadata.gz: ce836aa13bef0faf0023d66ba3c5fcb0dca6447e872df581110221fe38ba5991
+  data.tar.gz: 191dba3b66205f9bf29b4095d53681a70c1a9db1d00698ebacc0a38878306295
 SHA512:
-  metadata.gz: 98a0b74ebcdadafc34b6cecca41b456a91d63d710db9b1cef039c825f806c408abc79182dc359cfdb28a55ca4d5afeabae2cab12708d2946f44347b4ce8f9f1d
-  data.tar.gz: e95d1f143923f738312910efc6849a488cb7c8a20bae952d770d8b6bc704822af4b7b9b2c7c8e934213a5914e58f9655ea3147591fdb790558209d67753eece9
+  metadata.gz: 89c0377b952cd09fafb222248c25bb4d4e16a3a068ce40099c0106bd3ef623321fc5bbedb24e226e24d3ed2aaad13137f4d5d69093ea5520906b93cbd320e43a
+  data.tar.gz: fa29db6a3865b528aeef22bd187db14c9cd737efcd6f8fc202d47857e4b4d3454e19794937e40c1d4ec410010007e3bb2fe9a72c89eafe0da602fe382d63c144

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

@@ -14,28 +14,39 @@ def update
 	project = Utopia::Project::Base.new(context.root)
 	
 	FileUtils.mkdir_p self.context_root
-	index = {}
+	files = []
 	
-	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
+	# 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 index.any?
+	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 index
+	return nil
 end
 
 private

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

@@ -13,7 +13,7 @@ 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
@@ -42,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)

data/context/getting-started.md

@@ -1,15 +1,17 @@
 # Getting Started
 
-This guide explains how to use `utopia-project` for your own project.
+This guide explains how to use `utopia-project` to add documentation to your project.
 
 ## Installation
 
-Firstly, add the gem to your project:
+Add the gem to your project:
 
 ~~~ bash
 $ bundle add utopia-project
 ~~~
 
+## Usage
+
 ## Start Local Server
 
 Start the local server to preview documentation:

data/context/github-pages-integration.md

@@ -1,17 +1,67 @@
 # GitHub Pages Integration
 
-This guide shows you how to use `utopia-project` with GitHub Pages.
+This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.
 
-## Static Site Generation
+## Enable GitHub Pages
 
-Once you are happy with your project's documentation, use this command to generate a static site:
+In your GitHub project settings, you will need to [enable GitHub Pages from a custom GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow). Then, use the workflow below to publish the documentation:
 
-~~~ bash
-$ bake utopia:project:static
-~~~
+```yaml
+name: Documentation
 
-This will generate a static copy of your documentation into `docs/` which is what is required by GitHub Pages.
+on:
+  push:
+    branches:
+      - main
 
-## Enable GitHub Pages
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment:
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  BUNDLE_WITH: maintenance
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
 
-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).
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ruby
+        bundler-cache: true
+    
+    - name: Installing packages
+      run: sudo apt-get install wget
+    
+    - name: Generate documentation
+      timeout-minutes: 5
+      run: bundle exec bake utopia:project:static --force no
+    
+    - name: Upload documentation artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs
+  
+  deploy:
+    runs-on: ubuntu-latest
+    
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    
+    needs: generate
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```

data/context/index.yaml

@@ -1,16 +1,21 @@
 # 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:
+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
-  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:
+  description: This guide explains how to use `utopia-project` to add documentation
+    to your project.
+- path: documentation-guidelines.md
+  title: Documentation Guides
+  description: This guide explains how to create and maintain documentation for your
+    project using `utopia-project`.
+- path: github-pages-integration.md
   title: GitHub Pages Integration
-  order: 3
-  description: This guide shows you how to use `utopia-project` with GitHub Pages.
+  description: This guide shows you how to use `utopia-project` with GitHub Pages
+    to deploy documentation.

data/lib/utopia/project/base.rb

@@ -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

@@ -40,6 +40,31 @@ module Utopia
 				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/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.34.0"
+		VERSION = "0.35.0"
 	end
 end

data/readme.md

@@ -21,16 +21,20 @@ needs of my users.
 
 Please see the [project documentation](https://socketry.github.io/utopia-project/) for more details.
 
-  - [Getting Started](https://socketry.github.io/utopia-project/guides/getting-started/index) - This guide explains how to use `utopia-project` for your own project.
+  - [Getting Started](https://socketry.github.io/utopia-project/guides/getting-started/index) - This guide explains how to use `utopia-project` to add documentation to your project.
 
-  - [Documentation Formatting](https://socketry.github.io/utopia-project/guides/documentation-formatting/index) - This guide explains the conventions used by `utopia-project` when generating documentation for your project.
+  - [Documentation Guides](https://socketry.github.io/utopia-project/guides/documentation-guidelines/index) - This guide explains how to create and maintain documentation for your project using `utopia-project`.
 
-  - [GitHub Pages Integration](https://socketry.github.io/utopia-project/guides/github-pages-integration/index) - This guide shows you how to use `utopia-project` with GitHub Pages.
+  - [GitHub Pages Integration](https://socketry.github.io/utopia-project/guides/github-pages-integration/index) - This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.
 
 ## Releases
 
 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.

data/releases.md

@@ -1,5 +1,9 @@
 # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Samuel Williams