utopia-project 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d1ad15923d59f832f9be9b32a296003f285d38b95da13ac831575dc034a6c08
-  data.tar.gz: 3029c9fac2566ca56590ec6f15761218a0ecae564b1c55d75f2d9b6cb692a6bc
+  metadata.gz: 5ab639a6ea814e5195fb740583a00a28f55d6e18d86cb46a61341b7768ac4804
+  data.tar.gz: 4988213ac4168bb50ec1201e0cdd24c0d423b92092933546a7fa99f1e002f015
 SHA512:
-  metadata.gz: fabe143fac57289c5c273db880f66e4e2502da748b9179bb81cfe0eea38bb15d93dc042e12c2e95c1dec13b8d9cdafc108e50b1a9d8e42d5ad5955be47657788
-  data.tar.gz: '093c1ad0f1570461d66980065a982e3acf3286a8c67d4d94d9d57d83b09b7a8f1efe149ba8042a8d23b782c0acc0c2ad73c2bbcbf6787d98a951d305dbe9710a'
+  metadata.gz: 2b58e868cd25562bf2e17aaffdf2cfb830a72d888cf1106edebbe6edef5ba88f07b9f94c0de58d2fd18705401e40694b36725d2cbd925f19197bd9b753f0c782
+  data.tar.gz: b60d7c5fc718544aec358b953507eec731c5e93fa460e7172500a5b2414d33e2ec5456806effa8609e525ce85377c6c43a1bdb481c4a77c02d52b80b9eb8c380

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

@@ -0,0 +1,56 @@
+
+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
+	if metadata = gemspec.metadata
+		if documentation_uri = metadata['documentation_uri']
+			return documentation_uri
+		end
+	end
+	
+	return 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.23.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.23.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-06-15 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
@@ -218,10 +220,13 @@ files:
 - pages/source/controller.rb
 - pages/source/index.xnode
 - pages/source/show.xnode
+- public/.DS_Store
 - public/.nojekyll
+- public/_components/.DS_Store
 - public/_components/jquery-litebox/jquery.litebox.css
 - public/_components/jquery-litebox/jquery.litebox.gallery.css
 - public/_components/jquery-litebox/jquery.litebox.js
+- public/_components/jquery-syntax/.DS_Store
 - public/_components/jquery-syntax/base/jquery.syntax.brush.apache.css
 - public/_components/jquery-syntax/base/jquery.syntax.brush.applescript.css
 - public/_components/jquery-syntax/base/jquery.syntax.brush.assembly.css
@@ -292,6 +297,7 @@ files:
 - public/_components/jquery/jquery.slim.js
 - public/_components/jquery/jquery.slim.min.js
 - public/_components/jquery/jquery.slim.min.map
+- public/_components/mermaid/.DS_Store
 - public/_components/mermaid/mermaid.min.js
 - public/_components/mermaid/mermaid.min.js.map
 - public/_static/icon.png
@@ -322,7 +328,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.7
 signing_key:
 specification_version: 4
 summary: A project documentation tool based on Utopia.