utopia-project 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb8a529c1cca5ba878e32e433757429ad8bbcda4f6355242b11caba109595825
-  data.tar.gz: 120aca31fec8a99abd38d002ea890f282228e198406424cdaec874a16d30188d
+  metadata.gz: 85b28d4f829a2a136cfecc1d3eb56f969f12120dc3811f854eea5969970cf662
+  data.tar.gz: a5d2f5460d383fbc2260f14145e01ca8dcd0ababf874ba6a4ea899236457b14a
 SHA512:
-  metadata.gz: f611f36fb5cde35ae5943177cc101f619c9251cfb66edc47ecdca7fca21af75410e9c8dd0378951f8df1f1470601bdd7c8e0fc3b92808ae82ec91de8e7e4199a
-  data.tar.gz: dbae08da7898f04c8fef56e04a9eac068a3f4fdf4b141e976498a72c83ce11ff4ccf18ca1aec2f73c4f43a127d995f3f8aba2a740a78dbe611e3f52498847a23
+  metadata.gz: 880f4b5705451fa21fcf48042ed447b0265ac75e12c877a5683b87c939f2185f57858fc066aae39110ed48e69f04f57b76c2af8b38b6bd08df8f95e15c22091b
+  data.tar.gz: 56504db1b9b96fa279d91aa99beb3c3a0fcb9f5c00e918857b2c6247681c9406f4f77c1e0c166721449b319c46c71f50fc37d1c68102a0da5856dad5c6a146fa

data/bake/utopia/project.rb

@@ -11,8 +11,8 @@ end
 # Serve the project using a web server.
 # Binds to `https://localhost:9292` by default.
 #
-# @param port [Integer] The port to bind to.
-# @param bind [String] The URL to bind to, e.g. `http://localhost:80`.
+# @parameter port [Integer] The port to bind to.
+# @parameter bind [String] The URL to bind to, e.g. `http://localhost:80`.
 def serve(port: nil, bind: nil)
 	config_path = File.expand_path("../../template/config.ru", __dir__)
 	preload_path = File.expand_path("../../template/preload.rb", __dir__)
@@ -31,7 +31,7 @@ def serve(port: nil, bind: nil)
 end
 
 # Generate a static copy of the site.
-# @param output_path [String] The output path for the static site.
+# @parameter output_path [String] The output path for the static site.
 def static(output_path: "docs")
 	require 'rackula/command'
 	

data/lib/utopia/project/base.rb

@@ -51,7 +51,7 @@ module Utopia
 			end
 			
 			# Initialize the project with the given root path.
-			# @param root [String] The file-system path to the root of the project.
+			# @parameter root [String] The file-system path to the root of the project.
 			def initialize(root = Dir.pwd)
 				@root = root
 				
@@ -63,13 +63,16 @@ module Utopia
 			end
 			
 			# The file-system path to the root of the project.
+			# @attribute [String]
 			attr :root
 			
 			# The source code index which is used for generating pages.
+			# @attribute [Decode::Index]
 			attr :index
 			
 			# Return the absolute path for the given file name, if it exists in the project.
-			# @param file_name [String] The relative path to the project file, e.g. `README.md`.
+			# @parameter file_name [String] The relative path to the project file, e.g. `README.md`.
+			# @returns [String] The file-system path.
 			def path_for(file_name)
 				full_path = File.expand_path(file_name, @root)
 				if File.exist?(full_path)
@@ -78,28 +81,35 @@ module Utopia
 			end
 			
 			# Update the index with the specified paths.
-			# @param paths [Array(String)] The paths to load and parse.
+			# @parameter paths [Array(String)] The paths to load and parse.
 			def update(paths)
 				@index.update(paths)
 			end
 			
-			def best(symbols)
-				symbols.each do |symbol|
-					if symbol.documentation
-						return symbol
+			# Given an array of defintions, return the best definition for the purposes of generating documentation.
+			# @returns [Decode::Definition | Nil]
+			def best(definitions)
+				definitions.each do |definition|
+					if definition.documentation
+						return definition
 					end
 				end
 				
-				return symbols.first
+				return definitions.first
 			end
 			
+			# Given a lexical path, find the best definition for that path.
+			# @returns [Tuple(Decode::Trie::Node, Decode::Definition)]
 			def lookup(path)
 				if node = @index.trie.lookup(path.map(&:to_sym))
 					return node, best(node.values)
 				end
 			end
 			
-			def format(text, symbol = nil, language: symbol&.language)
+			# Format the given text in the context of the given definition and language.
+			# See {document} for details.
+			# @returns [Trenni::MarkupString]
+			def format(text, definition = nil, language: definition&.language)
 				case text
 				when Enumerable
 					text = text.to_a.join("\n")
@@ -107,29 +117,38 @@ module Utopia
 					return nil
 				end
 				
-				if document = self.document(text, symbol, language: language)
+				if document = self.document(text, definition, language: language)
 					return Trenni::MarkupString.raw(
 						document.to_html
 					)
 				end
 			end
 			
-			def document(text, symbol = nil, language: symbol&.language)
-				text = text&.gsub(/{(.*?)}/) do |match|
-					linkify($1, symbol, language: language)
+			# Convert the given markdown text into HTML.
+			#
+			# - Updates source code references (`{language identifier}`) into links.
+			# - Uses {Kramdown} to convert the text into HTML.
+			#
+			# @returns [Kramdown::Document]
+			def document(text, definition = nil, language: definition&.language)
+				text = text&.gsub(/(?<!`){(.*?)}/) do |match|
+					linkify($1, definition, language: language)
 				end
 				
 				return Kramdown::Document.new(text, syntax_highlighter: nil)
 			end
 			
-			def linkify(text, symbol = nil, language: symbol&.language)
+			# Replace source code references in the given text with HTML anchors.
+			#
+			# @returns [Trenni::Builder]
+			def linkify(text, definition = nil, language: definition&.language)
 				reference = @index.languages.parse_reference(text, default_language: language)
 				
 				Trenni::Builder.fragment do |builder|
-					if reference and definition = @index.lookup(reference, relative_to: symbol)&.first
+					if reference and definition = @index.lookup(reference, relative_to: definition)&.first
 						builder.inline('a', href: link_for(definition)) do
 							builder.inline('code', class: "language-#{definition.language.name}") do
-								builder.text definition.short_form
+								builder.text definition.qualified_form
 							end
 						end
 					elsif reference
@@ -145,26 +164,32 @@ module Utopia
 			end
 			
 			# Compute a unique string which can be used as `id` attribute in the HTML output.
-			def id_for(symbol, suffix = nil)
+			# @returns [String]
+			def id_for(definition, suffix = nil)
 				if suffix
-					"#{symbol.qualified_name}-#{suffix}"
+					"#{definition.qualified_name}-#{suffix}"
 				else
-					symbol.qualified_name
+					definition.qualified_name
 				end
 			end
 			
-			# Compute a link href to the given symbol for use within the HTML output.
-			def link_for(symbol)
-				path = symbol.lexical_path.map{|entry| entry.to_s}
+			# Compute a link href to the given definition for use within the HTML output.
+			# @returns [Trenni::Reference]
+			def link_for(definition)
+				path = definition.lexical_path.map{|entry| entry.to_s}
 				
-				if symbol.container?
+				if definition.container?
 					return Trenni::Reference.new(@source_path + path + "index")
 				else
 					name = path.pop
-					return Trenni::Reference.new(@source_path + path + "index", fragment: id_for(symbol))
+					return Trenni::Reference.new(@source_path + path + "index", fragment: id_for(definition))
 				end
 			end
 			
+			# Enumerate over all available guides in order.
+			# @block {|guide| ... }
+			# @yield guide [Guide]
+			# @returns [Enumerator(Guide)]
 			def guides
 				return to_enum(:guides) unless block_given?
 				

data/lib/utopia/project/guide.rb

@@ -30,8 +30,8 @@ module Utopia
 		# Provides structured access to a directory which contains documentation and source code to explain a specific process.
 		class Guide
 			# Initialize the example with the given root path.
-			# @param base [Base] The base instance for the project.
-			# @param root [String] The file-system path to the root of the example.
+			# @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)
 				@base = base
 				@root = root
@@ -46,25 +46,25 @@ module Utopia
 			end
 			
 			# The description from the first paragraph in the README.
-			# @attr [String | Nil]
+			# @attribute [String | Nil]
 			attr :description
 			
 			README = "README.md"
 			
+			# The path to the README file for the guide.
+			# @returns [String] The file-system path.
 			def readme_path
 				File.expand_path(README, @root)
 			end
 			
+			# Does a README file exist for this guide?
+			# @returns [Boolean]
 			def readme?
 				File.exist?(readme_path)
 			end
 			
-			def readme_document
-				content = File.read(self.readme_path)
-				
-				return @base.document(content)
-			end
-			
+			# The document for the README, if one exists.
+			# @returns [Kramdown::Document]
 			def document
 				if self.readme?
 					@document ||= self.readme_document.tap do |document|
@@ -89,31 +89,47 @@ module Utopia
 			end
 			
 			# The base instance of the project this example is loaded from.
+			# @attribute [Base]
 			attr :base
 			
 			# The file-system path to the root of the project.
+			# @attribute [String]
 			attr :root
 			
+			# The name of the guide.
+			# @returns [String]
 			def name
 				File.basename(@root)
 			end
 			
+			# The title of the guide.
+			# @returns [String]
 			def title
 				@title || Trenni::Strings.to_title(self.name)
 			end
 			
+			# The hypertext reference to this guide.
+			# @returns [String]
 			def href
 				"/guides/#{self.name}/index"
 			end
 			
+			# The best documentation, extracted from the source files of the guide.
+			# @returns [Decode::Documentation]
 			def documentation
 				@documentation ||= self.best_documentation
 			end
 			
+			# All files associated with this guide.
+			# @returns [Array(String)] The file-system paths.
 			def files
 				Dir.glob(File.expand_path("*", @root))
 			end
 			
+			# All the source files associated with this guide.
+			# @block {|source| ... } If a block is given.
+			# @yield source [Decode::Source]
+			# @returns [Enumerator(Decode::Source)] If no block is given.
 			def sources
 				return to_enum(:sources) unless block_given?
 				
@@ -126,6 +142,12 @@ module Utopia
 			
 			private
 			
+			def readme_document
+				content = File.read(self.readme_path)
+				
+				return @base.document(content)
+			end
+			
 			def best_documentation
 				if source = sources.first
 					if segment = source.segments.first

data/lib/utopia/project/version.rb

@@ -22,6 +22,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.7.1"
+		VERSION = "0.8.0"
 	end
 end

data/lib/utopia/project.rb

@@ -41,9 +41,9 @@ module Utopia
 		
 		# Appends a project application to the rack builder.
 		#
-		# @param builder [Rack::Builder]
-		# @param root [String] The file-system root path of the project/gem.
-		# @param locales [Array(String)] an array of locales to support, e.g. `['en', 'ja']`.
+		# @parameter builder [Rack::Builder]
+		# @parameter root [String] The file-system root path of the project/gem.
+		# @parameter locales [Array(String)] an array of locales to support, e.g. `['en', 'ja']`.
 		def self.call(builder, root = Dir.pwd, locales: nil)
 			if UTOPIA.production?
 				# Handle exceptions in production with a error page and send an email notification:

data/pages/_usage.xnode

@@ -9,8 +9,8 @@
 ?>
 	<h3><a href="#{guide.href}">#{guide.title}</a></h3>
 	
-	<?r if description = guide.documentation&.description ?>
-		#{base.format(description.first, language: guide.documentation.language)}
+	<?r if documentation = guide.documentation ?>
+		#{base.format(documentation.details, language: guide.documentation.language)}
 	<?r elsif description = guide.description ?>
 		#{MarkupString.raw Kramdown::Document.new(description, syntax_highlighter: nil).to_html}
 	<?r else ?>

data/pages/guides/show.xnode

@@ -14,7 +14,7 @@
 			?><h2><code>#{File.basename source.path}</code></h2><?r
 			source.segments.each do |segment|
 				if documentation = segment.documentation
-					?>#{base.format(documentation.description, language: source.language)}<?r
+					?>#{base.format(documentation.text, language: source.language)}<?r
 				end
 				
 				?><pre><code class="language-#{source.language.name}">#{segment.code}</code></pre><?r

data/pages/source/_signature.xnode

@@ -0,0 +1,40 @@
+<?r
+	base = self[:base]
+	symbol = self[:symbol]
+	documentation = symbol&.documentation
+	
+	if documentation.children?
+?>
+<details open>
+	<summary><h4>Signature</h4></summary>
+	<dl><?r
+		documentation.traverse do |node, descend|
+			node.each do |child|
+				?><dt>
+					<strong>#{child.directive}</strong><?r
+						case child
+						when Decode::Comment::Parameter
+							?>　<code class="syntax">#{child.name}</code>　#{base.linkify(child.type, symbol)}<?r
+						when Decode::Comment::Returns
+							?>　#{base.linkify(child.type, symbol)}<?r
+						when Decode::Comment::Yields
+							?>　<code class="syntax language-#{symbol.language.name}">#{child.block}</code><?r
+						end
+				?></dt><?r
+				
+				if text = child.text
+					?><dd>#{base.format(text, symbol)}</dd><?r
+				end
+				
+				if child.children?
+					?><dd><dl>
+						<?r descend.call(child) ?>
+					</dl></dd><?r
+				end
+			end
+		end
+	?></dl>
+</details>
+<?r
+	end
+?>

data/pages/source/index.xnode

@@ -15,7 +15,7 @@
 						<a href="#{base.link_for(symbol)}"><code class="language-#{symbol.language.name}">#{symbol.long_form}</code></a>
 						
 						<?r if documentation ?>
-							#{base.format(documentation.description.first, symbol)}
+							#{base.format(documentation.details, symbol)}
 						<?r end ?>
 						
 						<?r if symbol.container?

data/pages/source/show.xnode

@@ -1,15 +1,15 @@
 <content:page>
 	<?r
-	base = controller[:base]
-	node = controller[:node]
-	symbol = controller[:symbol]
+	base = self[:base]
+	node = self[:node]
+	symbol = self[:symbol]
 	?>
 	<content:heading><code class="language-#{symbol.language.name}">#{symbol.qualified_name}</code></content:heading>
 	
 	<main>
 		<?r
 		if documentation = symbol.documentation
-			?>#{base.format(documentation.description.to_a.join("\n"), symbol)}<?r
+			?>#{base.format(documentation.text.join("\n"), symbol)}<?r
 		end
 		?>
 		
@@ -38,25 +38,8 @@
 					?><h3 id="#{base.id_for(symbol)}"><code class="language-#{symbol.language.name}">#{symbol.long_form}</code></h3><?r
 					
 					if documentation = symbol.documentation
-						?>#{base.format(documentation.description, symbol)}<?r
-					end
-					
-					parameters = documentation.parameters.to_a
-					
-					if parameters.any?
-					?><details open>
-							<summary><h4>Parameters</h4></summary>
-							<dl><?r
-							parameters.each do |parameter|
-							?>
-								<dt><code class="syntax">#{parameter[:name]}</code> &mdash; #{base.linkify(parameter[:type], symbol)}</dt>
-								<?r if details = parameter[:details] ?>
-									<dd>#{base.format(parameter[:details], symbol)}</dd>
-								<?r end ?>
-							<?r
-							end
-						?></dl>
-						</details><?r
+						?>#{base.format(documentation.text, symbol)}<?r
+						?>#{partial 'content:signature', symbol: symbol}<?r
 					end
 					
 					if symbol.multiline?

data/public/_static/site.css

@@ -13,15 +13,26 @@ html {
 		font-size: 18px;
 		--tab-size: 4;
 	}
+	
+	main > pre {
+		margin: 2rem;
+	}
 }
 
 @media (min-width: 80em) {
 	html {
 		font-size: 20px;
-		--tab-size: 4;
 	}
 }
 
+p code {
+	padding: 0 0.2rem;
+}
+
+p code:first-child, p code:last-child {
+	padding: 0;
+}
+
 pre {
 	/* -moz-tab-size is still required by Firefox */
 	--tab-size: 2;
@@ -96,10 +107,14 @@ nav {
 	color: #aaa;
 }
 
-li {
+li, dt, dd {
 	margin: 0.5rem 0;
 }
 
+details dt, details dd {
+	margin: 1rem 0;
+}
+
 ul.index {
 	padding: 0;
 	list-style: none;

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-09 00:00:00.000000000 Z
+date: 2020-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: utopia
@@ -185,23 +185,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".editorconfig"
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- ".yarnrc"
-- README.md
 - bake/utopia/project.rb
-- gems.rb
-- guides/documentation-formatting/README.md
-- guides/getting-started/README.md
-- guides/github-pages-integration/README.md
-- guides/links.yaml
 - lib/utopia/project.rb
 - lib/utopia/project/base.rb
 - lib/utopia/project/guide.rb
 - lib/utopia/project/version.rb
-- package.json
 - pages/_heading.xnode
 - pages/_navigation.xnode
 - pages/_page.xnode
@@ -215,10 +203,10 @@ files:
 - pages/guides/show.xnode
 - pages/index.xnode
 - pages/links.yaml
+- pages/source/_signature.xnode
 - pages/source/controller.rb
 - pages/source/index.xnode
 - pages/source/show.xnode
-- public/.nojekyll
 - public/_components/jquery-litebox/jquery.litebox.css
 - public/_components/jquery-litebox/jquery.litebox.gallery.css
 - public/_components/jquery-litebox/jquery.litebox.js
@@ -297,8 +285,6 @@ files:
 - template/Gemfile
 - template/config.ru
 - template/preload.rb
-- utopia-project.gemspec
-- yarn.lock
 homepage: https://github.com/socketry/utopia-project
 licenses:
 - MIT
@@ -309,9 +295,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.editorconfig

@@ -1,13 +0,0 @@
-root = true
-
-[*]
-indent_style = tab
-indent_size = 2
-
-[*.md]
-indent_style = tab
-indent_size = 2
-
-[.*]
-indent_style = tab
-indent_size = 2

data/.github/workflows/development.yml

@@ -1,62 +0,0 @@
-name: Development
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ${{matrix.os}}-latest
-    continue-on-error: ${{matrix.experimental}}
-    
-    strategy:
-      matrix:
-        os:
-          - ubuntu
-          - macos
-        
-        ruby:
-          - 2.5
-          - 2.6
-          - 2.7
-        
-        experimental: [false]
-        env: [""]
-        
-        include:
-          - os: ubuntu
-            ruby: truffleruby
-            experimental: true
-            env: JRUBY_OPTS="--debug -X+O"
-          - os: ubuntu
-            ruby: jruby
-            experimental: true
-          - os: ubuntu
-            ruby: head
-            experimental: true
-          - os: ubuntu
-            ruby: 2.6
-            experimental: false
-            env: COVERAGE=PartialSummary,Coveralls
-    
-    steps:
-    - uses: actions/checkout@v1
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-    
-    - name: Installing packages (ubuntu)
-      if: matrix.os == 'ubuntu'
-      run: sudo apt-get install wget pkg-config
-    
-    - name: Installing packages (macos)
-      if: matrix.os == 'macos'
-      run: brew install wget pkg-config
-    
-    - name: Install dependencies
-      run: ${{matrix.env}} bundle install
-    
-    - name: Run tests
-      timeout-minutes: 5
-      run: |
-        git config --global user.email "samuel@oriontransfer.net"
-        git config --global user.name "Samuel Williams"
-        ${{matrix.env}} bundle exec rspec

data/.gitignore

@@ -1,17 +0,0 @@
-# Development specific:
-/.rspec_status
-/.bundle
-/pkg
-/gems.locked
-
-# Temporary data should not be added to the repository:
-/tmp
-
-# Node modules are 3rd party dependencies which can be fetched easily:
-/node_modules
-
-# This file should only ever exist on production, and may contain sensitive information:
-/config/environment.yaml
-
-# Ignore resized gallery photos:
-/public/_gallery

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---require spec_helper

data/.yarnrc

@@ -1 +0,0 @@
---modules-folder lib/components

data/README.md

@@ -1,54 +0,0 @@
-# Utopia::Project
-
-A simple Ruby project documentation website.
-
-## 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.
-
-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.
-
-## Usage
-
-Please see the <a href="https://socketry.github.io/utopia-project/">project documentation</a> or run it locally using `bake utopia:project:serve`.
-
-## Contributing
-
-We welcome contributions to this project.
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## 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.
-
-## License
-
-Released under the MIT license.
-
-Copyright, 2020, by [Samuel G. D. Williams](http://www.codeotaku.com).
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

data/gems.rb

@@ -1,4 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in utopia-project.gemspec
-gemspec

data/guides/documentation-formatting/README.md

@@ -1,55 +0,0 @@
-# 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
-
-#### `@param`
-
-The `@param` tag is used to describe the parameters of a method:
-
-~~~ ruby
-# @param x [Integer] The x co-ordinate.
-# @param y [Integer] The y co-ordinate.
-def move(x, y)
-	# ...
-end
-~~~
-
-#### `@return`
-
-The `@return` tag is used to describe the return type of the definition:
-
-~~~ ruby
-# @return [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.

data/guides/getting-started/README.md

@@ -1,31 +0,0 @@
-# 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/guides/github-pages-integration/README.md

@@ -1,17 +0,0 @@
-# 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, simply 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/guides/links.yaml

@@ -1,6 +0,0 @@
-getting-started:
-  order: 1
-documentation-formatting:
-  order: 2
-github-pages-integration:
-  order: 3

data/package.json

@@ -1,6 +0,0 @@
-{
-  "dependencies": {
-    "jquery-litebox": "^1.0.2",
-    "jquery-syntax": "^4.1.1"
-  }
-}

data/utopia-project.gemspec

@@ -1,35 +0,0 @@
-require_relative 'lib/utopia/project/version'
-
-Gem::Specification.new do |spec|
-	spec.name = "utopia-project"
-	spec.version = Utopia::Project::VERSION
-	spec.authors = ["Samuel Williams"]
-	spec.email = ["samuel.williams@oriontransfer.co.nz"]
-	
-	spec.summary = "A project documentation tool based on Utopia."
-	spec.homepage = "https://github.com/socketry/utopia-project"
-	spec.license = "MIT"
-	
-	spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
-		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(docs|test|spec|features)/}) }
-	end
-	
-	spec.require_paths = ["lib"]
-	
-	spec.add_dependency "utopia", "~> 2.14"
-	# spec.add_dependency "utopia-gallery"
-	
-	spec.add_dependency "kramdown"
-	spec.add_dependency "decode", "~> 0.13"
-	spec.add_dependency "rackula"
-	spec.add_dependency "falcon"
-	spec.add_dependency "thread-local"
-	
-	spec.add_development_dependency 'async-rspec'
-	spec.add_development_dependency 'rack-test'
-	
-	spec.add_development_dependency 'covered'
-	spec.add_development_dependency 'bundler'
-	spec.add_development_dependency 'rspec'
-	spec.add_development_dependency 'bake-bundler'
-end

data/yarn.lock

@@ -1,22 +0,0 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# yarn lockfile v1
-
-
-jquery-litebox@^1.0.2:
-  version "1.0.2"
-  resolved "https://registry.yarnpkg.com/jquery-litebox/-/jquery-litebox-1.0.2.tgz#122caec1e8ec1452f88d1d3eb3dd6f541f3f98c9"
-  integrity sha1-EiyuwejsFFL4jR0+s91vVB8/mMk=
-  dependencies:
-    jquery ">=1.4.1"
-
-jquery-syntax@^4.1.1:
-  version "4.1.1"
-  resolved "https://registry.yarnpkg.com/jquery-syntax/-/jquery-syntax-4.1.1.tgz#8e15d85952cfee02dda579564eef4b813e5fe4f9"
-  integrity sha512-W7HqdQV37N2r9JISW90liYaRNzam++0+zt3gFGzkAa/l4eHF11vyOKBhsadEhewYKBOsWSVIXqdcLtAxYgwT+g==
-  dependencies:
-    jquery ">=1.4.1"
-
-jquery@>=1.4.1:
-  version "3.5.0"
-  resolved "https://registry.yarnpkg.com/jquery/-/jquery-3.5.0.tgz#9980b97d9e4194611c36530e7dc46a58d7340fc9"
-  integrity sha512-Xb7SVYMvygPxbFMpTFQiHh1J7HClEaThguL15N/Gg37Lri/qKyhRGZYzHRyLH8Stq3Aow0LsHO2O2ci86fCrNQ==