class Base

Extends
Thread::Local

Provides structured access to a project directory which contains source code and guides.

Usage

To get an instance for the current project, use Base#instance.

Definitions

def self.local

Load the current project and index its Ruby source files.

Signature
returns　Base

The loaded project.

Implementation

 
def self.local
	instance = self.new
	
	source_files = Dir.glob(
		File.expand_path("{lib,app}/**/*.rb", instance.root)
	)
	
	instance.update(source_files)
	
	return instance
end

def initialize(root = Dir.pwd)

Initialize the project with the given root path.

Signature
parameter　root　String

The file-system path to the root of the project.

Implementation

 
def initialize(root = Dir.pwd)
	@root = root
	
	@reference_path = Utopia::Path["/reference"]
	
	@index = Decode::Index.new
	
	@links = Utopia::Content::Links.new(@root)
end

attr :root

The file-system path to the root of the project.

Signature
attribute　String

attr :index

The source code index which is used for generating pages.

Signature
attribute　Decode::Index

def path_for(file_name)

Return the absolute path for the given file name, if it exists in the project.

Example: Get README path

 
base = Utopia::Project::Base.new
base.path_for("readme.md") # => "/path/to/project/readme.md" or nil

Signature
parameter　file_name　String

The relative path to the project file, e.g. readme.md.

returns　String

The file-system path.

Implementation

 
def path_for(file_name)
	full_path = File.expand_path(file_name, @root)
	if File.exist?(full_path)
		return full_path
	end
end

def update(paths)

Update the index with the specified paths.

Signature
parameter　paths　Array(String)

The paths to load and parse.

Implementation

 
def update(paths)
	@index.update(paths)
end

def best(definitions)

Given an array of defintions, return the best definition for the purposes of generating documentation.

Signature
returns　Decode::Definition | Nil

Implementation

 
def best(definitions)
	definitions.each do |definition|
		if definition.documentation
			return definition
		end
	end
	
	return definitions.first
end

def lookup(path)

Given a lexical path, find the best definition for that path.

Example: Lookup a definition

 
base = Utopia::Project::Base.local
_, definition = base.lookup(%i[Utopia Project Base])

Signature
returns　Tuple(Decode::Trie::Node, Decode::Definition)

Implementation

 
def lookup(path)
	if node = @index.trie.lookup(path.map(&:to_sym))
		return node, best(node.values)
	end
end

def document_for(definition)

Load the supplemental document associated with a definition.

Signature
parameter　definition　Decode::Definition

The definition to load documentation for.

returns　Document | Nil

The supplemental document, if it exists.

Implementation

 
def document_for(definition)
	document_path = File.join("lib", definition.lexical_path.map{|_| _.to_s.downcase}) + ".md"
	
	if File.exist?(document_path)
		document = self.document(File.read(document_path), definition)
		
		if document.first_child.type == :header
			document.first_child.delete
		end
		
		return document
	end
end

def linkify(text, definition, language: definition&.language)

Format source text with links to referenced definitions.

Signature
parameter　text　String

The source text to format.

parameter　definition　Decode::Definition

The definition that provides the lexical context.

parameter　language　Decode::Language::Generic

The source language.

returns　String

The formatted source code markup.

Implementation

 
def linkify(text, definition, language: definition&.language)
	rewriter = Linkify.new(self, language, text)
	
	code = language.code_for(text, @index, relative_to: definition)
	
	code.extract(rewriter)
	
	return rewriter.apply
end

def format(text, definition = nil, language: definition&.language, **options)

Format the given text in the context of the given definition and language. See Utopia::Project::Base#document for details.

Example: Format text with code links

 
base = Utopia::Project::Base.new
base.format("See ruby:`Utopia::Project::Base#guides`.") # => XRB::MarkupString

Signature
returns　XRB::MarkupString

Implementation

 
def format(text, definition = nil, language: definition&.language, **options)
	if document = self.document(text, definition, language: language)
		return XRB::Markup.raw(
			document.to_html(**options)
		)
	end
end

def document(text, definition = nil, language: definition&.language)

Convert the given markdown text into HTML.

Updates language-prefixed inline code (e.g. ruby: followed by inline code) into links.

Example: Convert markdown to HTML

 
base = Utopia::Project::Base.new
doc = base.document("# Title")
doc.to_html # => "<h1>Title</h1>\n"

Signature
returns　Document

Implementation

 
def document(text, definition = nil, language: definition&.language)
	case text
	when Enumerable
		text = text.to_a.join("\n")
	when nil
		return nil
	end
	
	Document.new(text, self, definition: definition, default_language: language)
end

def id_for(definition, suffix = nil)

Compute a unique string which can be used as id attribute in the HTML output.

Example: Compute id for a definition

 
base = Utopia::Project::Base.local
_, definition = base.lookup(%i[Utopia Project Base])
base.id_for(definition) # => "Utopia::Project::Base"

Signature
returns　String

Implementation

 
def id_for(definition, suffix = nil)
	if suffix
		"#{definition.qualified_name}-#{suffix}"
	else
		definition.qualified_name
	end
end

def inheritance_for(definition)

Resolve inheritance information for the given definition.

Signature
parameter　definition　Decode::Definition

The definition to inspect.

returns　Inheritance

The inheritance information.

Implementation

 
def inheritance_for(definition)
	Inheritance.new(@index, definition)
end

def guides

Get the guides collection for this project.

Example: List guide titles

 
base = Utopia::Project::Base.new
base.guides.each do |guide|
	puts guide.title
end

Signature
returns　Guides

Implementation

 
def guides
	@guides ||= Guides.new(self, @links)
end

def readme_document

Load the project README document.

Signature
returns　Document | Nil

The README document, if one exists.

Implementation

 
def readme_document
	if path = self.path_for("readme.md") || self.path_for("README.md")
		Document.new(File.read(path), self)
	end
end

def project_title

Get the project title from its README.

Signature
returns　String

The project title, or a generic fallback.

Implementation

 
def project_title
	readme_document&.title || "Project"
end

def releases_document

Load the project release notes document.

Signature
returns　ReleasesDocument | Nil

The release notes document, if one exists.

Implementation

 
def releases_document
	if path = self.path_for("releases.md")
		ReleasesDocument.new(File.read(path), self)
	end
end

def releases

Enumerate the project releases.

Signature
returns　Enumerator(ReleasesDocument::Release) | Nil

The releases, if release notes exist.

Implementation

 
def releases
	if releases_document = self.releases_document
		releases_document.releases
	end
end

def gemspec

Load and return the gemspec for this project.

Signature
returns　Gem::Specification | nil

The loaded gemspec, or nil if not found.

Implementation

 
def gemspec
	if gemspec_path = self.gemspec_path
		@gemspec ||= ::Gem::Specification.load(File.join(@root, gemspec_path))
	end
end

def source_code_uri

Return the source code URI for this project, if available. Prefers metadata["source_code_uri"] over homepage.

Signature
returns　String | nil

Implementation

 
def source_code_uri
	gemspec&.metadata&.dig("source_code_uri") || gemspec&.homepage
end