utopia-project 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7571eadd6ab883d2405f012181f6079c01c3775a9678e8529920b7768445c7b3
-  data.tar.gz: 967608452801fd109a543d90d0b5bc7d5020148e90e2ccf9d87052160f43a893
+  metadata.gz: b31386125a2a1880b8d162ff278234e5c969b5ad658639e93ecf543b259b55d5
+  data.tar.gz: 35cab271274f82f93153d527631c3798342c5f08e2dd8a1e317a521730b89866
 SHA512:
-  metadata.gz: 832377189cf4125315baf88d81691e6dea3173cfdbef2a7ccb291cadb7fe8f62186561374d5295c2ee1f68860c4c5cd911c3a6409431acc70fae9de75cba5f45
-  data.tar.gz: c886453e9447576f9983f7dd476f09042bbb7df9ea1af627896ecee051162d276544e6d7f56b60bc2d3a2893f455210337f9af7eef677217870c59ca58dc5bce
+  metadata.gz: 98738871025a6afa851a009f41ea8a4d8cd47b54ace8ecf64fce5fe78b90e31e8bf0923ce9bed3ee2cd18de1a69e92e0b01d22ca61542dc68ed5d969c428758a
+  data.tar.gz: 96fa148979e16c1cea5d46c9ff8e669c4588b8183d47005bf6d3f41484aca4013232127c4dcbfea4dd12b7b2388895e35f70d83695ae1bcad72416d190967c18

data/bake/utopia/project/readme/releases.xrb

@@ -0,0 +1,11 @@
+<?r
+project.releases.each do |release|
+?>
+### #{release.name}
+
+<?r release.summary do |title| ?>
+  - [#{title}](#{release.href(documentation_url, title)})
+<?r
+	end
+end 
+?>

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

@@ -22,6 +22,16 @@ def update(path: "readme.md", documentation_url: nil)
 		end
 	end
 	
+	readme.replace_section("Releases", children: true) do |header|
+		current = header
+		
+		releases_section = self.releases_section(documentation_url, project)
+		releases_section.each do |child|
+			current.insert_after(child)
+			current = child
+		end
+	end
+	
 	File.write(path, readme.root.to_markdown)
 end
 
@@ -58,3 +68,12 @@ def usage_section(documentation_url, project)
 	
 	return Markly.parse(output)
 end
+
+def releases_section(documentation_url, project)
+	template = XRB::Template.load_file(File.expand_path("releases.xrb", __dir__))
+	scope = Scope.new(documentation_url, project)
+	
+	output = template.to_string(scope)
+	
+	return Markly.parse(output)
+end

data/changes.md

@@ -0,0 +1,5 @@
+# v0.28.0
+
+## Introduce Changes Document
+
+A new changes document, if present, will be used to display changes in the release notes. The changes document should be named `changes.md` and should be placed in the root of the project. The changes document should be written in markdown format.

data/lib/utopia/project/base.rb

@@ -13,6 +13,8 @@ require 'decode'
 require 'thread/local'
 
 require_relative 'document'
+require_relative 'changes_document'
+
 require_relative 'guide'
 require_relative 'linkify'
 
@@ -189,6 +191,18 @@ module Utopia
 			def project_title
 				readme_document&.title || "Project"
 			end
+			
+			def changes_document
+				if path = self.path_for('changes.md')
+					ChangesDocument.new(File.read(path), self)
+				end
+			end
+			
+			def releases
+				if changes_document = self.changes_document
+					changes_document.releases
+				end
+			end
 		end
 	end
 end

data/lib/utopia/project/changes_document.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2024, by Samuel Williams.
+
+require_relative 'document'
+
+module Utopia
+	module Project
+		class ChangesDocument < Document
+			class Release
+				def initialize(node)
+					@node = node
+				end
+				
+				def changes
+					return to_enum(:changes) unless block_given?
+					
+					node = @node.next
+					
+					while node
+						if node.type == :header
+							if node.header_level <= @node.header_level
+								break
+							end
+							
+							if node.header_level == @node.header_level + 1
+								yield node
+							end
+						end
+						
+						node = node.next
+					end
+				end
+				
+				def name
+					@node.to_plaintext.chomp
+				end
+				
+				def summary
+					return to_enum(:summary) unless block_given?
+					
+					changes.each do |node|
+						yield node.to_plaintext.chomp
+					end
+				end
+				
+				def href(base = "/", change)
+					"#{base}changes/index##{change.downcase.gsub(/\s+/, "-")}"
+				end
+			end
+			
+			def release_names
+				return to_enum(:release_names) unless block_given?
+				
+				self.root.each do |node|
+					if node.type == :header and node.header_level == 1
+						yield node.to_plaintext.chomp
+					end
+				end
+			end
+			
+			def release(name)
+				self.root.each do |node|
+					if node.type == :header and node.header_level == 1 and node.to_plaintext.chomp == name
+						return Release.new(node)
+					end
+				end
+			end
+			
+			def latest_release
+				if name = release_names.first
+					release(name)
+				end
+			end
+			
+			def releases
+				return to_enum(:releases) unless block_given?
+				
+				release_names.each do |name|
+					yield release(name)
+				end
+			end
+		end
+	end
+end

data/lib/utopia/project/document.rb

@@ -4,6 +4,7 @@
 # Copyright, 2020-2024, by Samuel Williams.
 
 require_relative 'renderer'
+require 'xrb'
 
 module Utopia
 	module Project
@@ -35,7 +36,7 @@ module Utopia
 				self.root.first_child
 			end
 			
-			def replace_section(name)
+			def replace_section(name, children: false)
 				child = self.first_child
 				
 				while child
@@ -48,7 +49,16 @@ module Utopia
 							current = header.next
 							
 							# Delete everything in the section until we encounter another header:
-							while current && current.type != :header
+							while current
+								if current.type == :header
+									# If we are removing all children, keep on going until we reach a header of the same level or higher:
+									if children
+										break if current.header_level <= header.header_level
+									else
+										break
+									end
+								end
+								
 								current_next = current.next
 								current.delete
 								current = current_next

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.27.0"
+		VERSION = "0.28.0"
 	end
 end

data/pages/changes/controller.rb

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

data/pages/changes/index.xnode

@@ -0,0 +1,13 @@
+<content:page>
+	<?r
+	if document = self[:document]
+		?>#{MarkupString.raw document.to_html}<?r
+	else
+		?>
+		<content:heading>Project</content:heading>
+		
+		<p>This project does not have a <code>changes.md</code> file.</p>
+		<?r
+	end
+	?>
+</content:page>

data/pages/index.xnode

@@ -34,5 +34,5 @@
 		<p>This project does not have a <code>readme.md</code> file.</p>
 		<?r
 	end
-	?>
+?>
 </content:page>

data/readme.md

@@ -21,14 +21,22 @@ 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` for your own 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 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.
 
-  - [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.
+
+## Releases
+
+### v0.28.0
+
+  - [Introduce Changes Document](https://socketry.github.io/utopia-project/changes/index#introduce-changes-document)
+
+## See Also
+
+  - [Utopia](https://github.com/socketry/utopia) — The website framework which powers this web application.
+  - [Decode](https://github.com/ioquatix/decode) — The source code parser and cross-referencing library.
 
 ## Contributing
 
@@ -47,8 +55,3 @@ In order to protect users of this project, we require all contributors to comply
 ### Community Guidelines
 
 This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
-
-## See Also
-
-  - [Utopia](https://github.com/socketry/utopia) — The website framework which powers this web application.
-  - [Decode](https://github.com/ioquatix/decode) — The source code parser and cross-referencing library.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-07-24 00:00:00.000000000 Z
+date: 2024-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: decode
@@ -133,11 +133,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bake/utopia/project.rb
+- bake/utopia/project/readme/releases.xrb
 - bake/utopia/project/readme/update.rb
 - bake/utopia/project/readme/usage.xrb
+- changes.md
 - lib/utopia/project.rb
 - lib/utopia/project/base.md
 - lib/utopia/project/base.rb
+- lib/utopia/project/changes_document.rb
 - lib/utopia/project/document.rb
 - lib/utopia/project/guide.rb
 - lib/utopia/project/linkify.rb
@@ -151,6 +154,8 @@ files:
 - pages/_thumbnail.xnode
 - pages/_usage.xnode
 - pages/_youtube-video.xnode
+- pages/changes/controller.rb
+- pages/changes/index.xnode
 - pages/controller.rb
 - pages/errors/exception.xnode
 - pages/errors/file-not-found.xnode
@@ -256,6 +261,7 @@ homepage: https://socketry.github.io/utopia-project
 licenses:
 - MIT
 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/
 post_install_message: