utopia-project 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6aa72e7117031702241752a366174d7bc8fa7a44ca0bbf52de399ef9c89173e4
+  data.tar.gz: b32f8ef78c132cfcb4cd414416aa0c7dd547e9253a989565f3446027003b55ef
+SHA512:
+  metadata.gz: 582d3f3051f7f0a304b4bf1c286eb22fc45bc9b8a87ef3cb5f51740553608cbef88a4d1d0db5cb442acc1d101884f4eb020e34e47c4fc466b47ca4bb312b7b9a
+  data.tar.gz: 264853fea075ef9d3f1b1787a3b9bd3c6f42364bb29378efbbbb6f9e501eb366655f4df26fbf740b74c02ff58e96560d21ae444909afb3e52eeb186929ba3879

data/.editorconfig

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,17 @@
+# 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

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

data/.yarnrc

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

data/README.md

@@ -0,0 +1,41 @@
+# Utopia::Project
+
+A simple Ruby project documentation website.
+
+## 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
+
+## 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/bake/utopia/project.rb

@@ -0,0 +1,32 @@
+
+# Create an empty project in the current directory.
+def create
+	template_path = File.expand_path("../../template/*", __dir__)
+	
+	Dir.glob(template_path) do |path|
+		FileUtils::Verbose.cp_r path, Dir.pwd
+	end
+end
+
+# Serve the project locally.
+def serve
+	config_path = File.expand_path("../../template/config.ru", __dir__)
+	preload_path = File.expand_path("../../template/preload.rb", __dir__)
+	
+	system("falcon", "serve", "--config", config_path, "--preload", preload_path)
+end
+
+def static(output_path: "docs")
+	require 'rackula/command'
+	
+	config_path = File.expand_path("../../template/config.ru", __dir__)
+	public_path = File.expand_path("../../public", __dir__)
+	
+	Rackula::Command::Top["generate", "--force",
+		"--config", config_path,
+		"--public", public_path,
+		"--output-path", output_path
+	].call
+	
+	FileUtils.touch File.expand_path(".nojekyll", output_path)
+end

data/gems.rb

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

data/guides/documentation-formatting/README.md

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

@@ -0,0 +1,17 @@
+# 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/lib/utopia/project/base.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# 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.
+
+require 'utopia/path'
+require 'trenni/reference'
+require 'decode'
+
+require 'thread/local'
+
+require 'kramdown'
+
+require_relative 'guide'
+
+module Utopia
+	module Project
+		# The base symbol table and project index.
+		class Base
+			extend Thread::Local
+			
+			def self.local
+				instance = self.new
+				
+				source_files = Dir.glob(
+					File.expand_path("lib/**/*.rb", instance.root)
+				)
+				
+				instance.update(source_files)
+				
+				return instance
+			end
+			
+			# Initialize the project with the given root path.
+			# @param root [String] The file-system path to the root of the project.
+			def initialize(root = Dir.pwd)
+				@root = root
+				
+				@source_path = Utopia::Path["/source"]
+				
+				@index = Decode::Index.new
+			end
+			
+			# The file-system path to the root of the project.
+			attr :root
+			
+			# The source code index which is used for generating pages.
+			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`.
+			def path_for(file_name)
+				full_path = File.expand_path(file_name, @root)
+				if File.exist?(full_path)
+					return full_path
+				end
+			end
+			
+			# Update the index with the specified paths.
+			# @param 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
+					end
+				end
+				
+				return symbols.first
+			end
+			
+			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)
+				if text.is_a?(Enumerable)
+					text = text.to_a.join("\n")
+				end
+				
+				if language
+					text = text&.gsub(/{(.*?)}/) do |match|
+						linkify($1, symbol, language: language)
+					end
+				end
+				
+				return Trenni::MarkupString.raw(
+					Kramdown::Document.new(text, syntax_highlighter: nil).to_html
+				)
+			end
+			
+			def linkify(text, symbol = nil, language: symbol&.language)
+				reference = language.reference(text)
+				
+				Trenni::Builder.fragment do |builder|
+					if definition = @index.lookup(reference, relative_to: symbol)&.first
+						builder.inline('a', href: link_for(definition)) do
+							builder.inline('code', class: "language-#{definition.language.name}") do
+								builder.text definition.short_form
+							end
+						end
+					else
+						builder.inline('code', class: "language-#{symbol.language.name}") do
+							builder.text text
+						end
+					end
+				end
+			end
+			
+			# Compute a unique string which can be used as `id` attribute in the HTML output.
+			def id_for(symbol)
+				symbol.qualified_name
+			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}
+				
+				if symbol.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))
+				end
+			end
+			
+			def guides
+				guides_root = File.expand_path("guides", @root)
+				
+				# There are no guides if there is no directory:
+				return unless File.directory?(guides_root)
+				
+				return to_enum(:guides) unless block_given?
+				
+				Dir.each_child(guides_root) do |entry|
+					guide_path = File.join(guides_root, entry)
+					
+					next unless File.directory?(guide_path)
+					
+					yield Guide.new(self, guide_path)
+				end
+			end
+		end
+	end
+end

data/lib/utopia/project/guide.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# 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.
+
+require 'utopia/path'
+require 'trenni/reference'
+require 'decode'
+require 'kramdown'
+
+module Utopia
+	module Project
+		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.
+			def initialize(base, root)
+				@base = base
+				@root = root
+				
+				@documentation = nil
+				
+				@document = nil
+				@title = nil
+				@description = nil
+				
+				self.document
+			end
+			
+			# The description from the first paragraph in the README.
+			# @attr [String | Nil]
+			attr :description
+			
+			README = "README.md"
+			
+			def readme_path
+				File.expand_path(README, @root)
+			end
+			
+			def readme?
+				File.exist?(readme_path)
+			end
+			
+			def document
+				if self.readme?
+					@document ||= Kramdown::Document.new(File.read(self.readme_path), syntax_highlighter: nil).tap do |document|
+						root = document.root
+						if element = root.children.first
+							if element.type == :header
+								@title = element.children.first.value
+								
+								# Remove the title:
+								root.children.shift
+								
+								# Remove any blank lines:
+								root.children.shift while root.children.first&.type == :blank
+								
+								# Read the description:
+								root.children.first.options[:encoding] = root.options[:encoding]
+								@description = Kramdown::Converter::Kramdown.convert(root.children.first).first
+							end
+						end
+					end
+				end
+			end
+			
+			# The base instance of the project this example is loaded from.
+			attr :base
+			
+			# The file-system path to the root of the project.
+			attr :root
+			
+			def name
+				File.basename(@root)
+			end
+			
+			def title
+				@title || Trenni::Strings.to_title(self.name)
+			end
+			
+			def href
+				"/guides/#{self.name}/index"
+			end
+			
+			def documentation
+				@documentation ||= self.best_documentation
+			end
+			
+			def files
+				Dir.glob(File.expand_path("*", @root))
+			end
+			
+			def sources
+				return to_enum(:sources) unless block_given?
+				
+				files.each do |path|
+					if source = Decode::Source.for?(path)
+						yield source
+					end
+				end
+			end
+			
+			private
+			
+			def best_documentation
+				if source = sources.first
+					if segment = source.segments.first
+						return segment.documentation
+					end
+				end
+			end
+		end
+	end
+end

data/lib/utopia/project/version.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# 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.
+
+module Utopia
+	module Project
+		VERSION = "0.1.0"
+	end
+end

data/lib/utopia/project.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# 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.
+
+require "utopia/project/version"
+
+require 'variant'
+
+require 'utopia/localization'
+require 'utopia/gallery'
+
+require_relative 'project/base'
+
+module Utopia
+	module Project
+		# The root directory of the web application files.
+		SITE_ROOT = File.expand_path("../..", __dir__)
+		
+		# The root directory for the utopia middleware.
+		PAGES_ROOT = File.expand_path("pages", SITE_ROOT)
+		
+		# The root directory for static assets.
+		PUBLIC_ROOT = File.expand_path("public", SITE_ROOT)
+		
+		# Appends a project application to the rack builder.
+		#
+		#	~~~ ruby
+		#	# In your `config.ru` file:
+		#	
+		#	require 'utopia/setup'
+		#	UTOPIA ||= Utopia.setup
+		#
+		#	require 'utopia/project'
+		#	Utopia::Project.call(self)
+		#	~~~
+		#
+		# @param 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:
+				builder.use Utopia::Exceptions::Handler
+				builder.use Utopia::Exceptions::Mailer
+			else
+				# We want to propate exceptions up when running tests:
+				builder.use Rack::ShowExceptions unless UTOPIA.testing?
+			end
+			
+			public_root = File.expand_path("public", root)
+			builder.use Utopia::Static, root: public_root
+			
+			builder.use Utopia::Static, root: PUBLIC_ROOT
+			
+			builder.use Utopia::Redirection::Rewrite, {
+				'/' => '/index'
+			}
+			
+			builder.use Utopia::Redirection::DirectoryIndex
+			
+			builder.use Utopia::Redirection::Errors, {
+				404 => '/errors/file-not-found'
+			}
+			
+			if locales
+				builder.use Utopia::Localization,
+					default_locale: locales.first,
+					locales: locales
+			end
+			
+			builder.use Utopia::Controller, root: PAGES_ROOT
+			
+			cache_root = File.expand_path("_gallery", root)
+			
+			builder.use Utopia::Content, root: PAGES_ROOT, namespaces: {
+				'gallery' => Utopia::Gallery::Tags.new
+			}
+			
+			builder.run lambda { |env| [404, {}, []] }
+		end
+	end
+end

data/package.json

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