utopia-project 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d1ad15923d59f832f9be9b32a296003f285d38b95da13ac831575dc034a6c08
-  data.tar.gz: 3029c9fac2566ca56590ec6f15761218a0ecae564b1c55d75f2d9b6cb692a6bc
+  metadata.gz: af7ac04b71cc8b501069888bd23a5da5cd00bd25d7900016fe89de7e08170426
+  data.tar.gz: fba0add2c28c7712a0c6fd894b21aca3f0015c3fc13f3c4b0299aa053e4dca9a
 SHA512:
-  metadata.gz: fabe143fac57289c5c273db880f66e4e2502da748b9179bb81cfe0eea38bb15d93dc042e12c2e95c1dec13b8d9cdafc108e50b1a9d8e42d5ad5955be47657788
-  data.tar.gz: '093c1ad0f1570461d66980065a982e3acf3286a8c67d4d94d9d57d83b09b7a8f1efe149ba8042a8d23b782c0acc0c2ad73c2bbcbf6787d98a951d305dbe9710a'
+  metadata.gz: 0fd2ed330c03e2ba6b4dc2f5ffa7c31d88b6c974b2e1b349c03d882b11ba22cca2fd86aafef63aa09dc18a75d14c1daf766c27b7791c1d3832a67fab00ac22fa
+  data.tar.gz: 6d03bc32040379cfab0f3125da19bc05a21a860cded807c695c8b0592b8b6766c200b489988f9f867a42ab4053e5885a839e66c9774321217f59a4d0c0ab0d98

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

@@ -0,0 +1,50 @@
+
+require 'utopia/project'
+require 'trenni'
+
+def update(path: "readme.md", documentation_url: nil)
+	project = Utopia::Project::Base.new(context.root)
+	readme = project.readme_document
+	
+	documentation_url ||= public_documentation_url
+	
+	readme.replace_section("Usage") do |header|
+		current = header
+		
+		usage_section = self.usage_section(documentation_url, project)
+		usage_section.each do |child|
+			current.insert_after(child)
+			current = child
+		end
+	end
+	
+	File.write(path, readme.root.to_markdown)
+end
+
+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
+	gemspec&.homepage
+end
+
+def usage_section(documentation_url, project)
+	template = Trenni::Template.load_file(File.expand_path("usage.trenni", __dir__))
+	scope = Scope.new(documentation_url, project)
+	
+	output = template.to_string(scope)
+	
+	return Markly.parse(output)
+end

data/bake/utopia/project/readme/usage.trenni

@@ -0,0 +1,5 @@
+Please see the [project documentation](#{documentation_url}) for more details.
+
+<?r project.guides.each do |guide| ?>
+- [#{guide.title}](#{guide.href(documentation_url)}) - #{guide.description.to_markdown}
+<?r end ?>

data/lib/utopia/project/document.rb

@@ -46,11 +46,12 @@ module Utopia
 						if header.first_child.to_plaintext.include?(name)
 							# Now subsequent children:
 							current = header.next
-
+							
 							# Delete everything in the section until we encounter another header:
 							while current && current.type != :header
+								current_next = current.next
 								current.delete
-								current = current.next
+								current = current_next
 							end
 							
 							return yield(header)

data/lib/utopia/project/guide.rb

@@ -83,8 +83,8 @@ module Utopia
 			
 			# The hypertext reference to this guide.
 			# @returns [String]
-			def href
-				"/guides/#{self.name}/index"
+			def href(base = "/")
+				"#{base}guides/#{self.name}/index"
 			end
 			
 			# The best documentation, extracted from the source files of the guide.

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.21.0"
+		VERSION = "0.22.0"
 	end
 end

data/readme.md

@@ -2,19 +2,33 @@
 
 A simple Ruby project documentation website.
 
-[![Development Status](https://github.com/socketry/utopia-project/workflows/Test/badge.svg)](https://github.com/socketry/utopia-project/actions?workflow=Test)
+[![Test](https://github.com/socketry/utopia-project/actions/workflows/test.yaml/badge.svg)](https://github.com/socketry/utopia-project/actions/workflows/test.yaml)
 
 ## Motivation
 
-I've used many documentation tools. Most are over-complicated and focus on what is possible rather than what is useful. Because I manage many open source projects, at a certain scale it makes sense to build something to suit your needs rather than try to adapt to existing systems. This is one such instance.
+I've used many documentation tools. Most are over-complicated and focus on what is possible rather than what is useful.
+Because I manage many open source projects, at a certain scale it makes sense to build something to suit your needs
+rather than try to adapt to existing systems. This is one such instance.
 
-My goal is to provide task-centric documentation, and to continually improve the way it's presented. The primary entry point for new developers are the structured usage guides, however having rich cross-referencing into the code is equally important.
+My goal is to provide task-centric documentation, and to continually improve the way it's presented. The primary entry
+point for new developers are the structured usage guides, however having rich cross-referencing into the code is equally
+important.
 
-With that in mind, this web application provides such a model and will evolve over time to suit my requirements and the needs of my users.
+With that in mind, this web application provides such a model and will evolve over time to suit my requirements and the
+needs of my users.
 
 ## Usage
 
-Please see the <a href="https://socketry.github.io/utopia-project/">project documentation</a> or run it locally using `bake utopia:project:serve`.
+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.
+
+  - [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.
 
 ## Contributing
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -39,7 +39,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2023-02-18 00:00:00.000000000 Z
+date: 2023-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: decode
@@ -188,6 +188,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bake/utopia/project.rb
+- bake/utopia/project/readme/update.rb
+- bake/utopia/project/readme/usage.trenni
 - lib/utopia/project.rb
 - lib/utopia/project/base.md
 - lib/utopia/project/base.rb
@@ -322,7 +324,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: A project documentation tool based on Utopia.