class Guide

Provides structured access to a directory which contains documentation and source code to explain a specific process.

Definitions

def initialize(base, root, metadata)

Initialize the example with the given root path.

Signature
parameter　base　Base

The base instance for the project.

parameter　root　String

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

Implementation

 
def initialize(base, root, metadata)
	@base = base
	@root = root
	@metadata = metadata
	
	@documentation = nil
	
	@document = nil
	@title = nil
	@description = nil
	
	self.document
end

attr :description

The description from the first paragraph in the README.

Signature
attribute　String | Nil

attr :metadata

The metadata associated with the guide.

Signature
attribute　Hash

def order

The explicit display order of the guide.

Signature
returns　Integer | Nil

Implementation

 
def order
	metadata[:order]
end

def <=>(other)

Compare guides by explicit order and then by name.

Signature
parameter　other　Guide

The other guide to compare.

returns　Integer

The comparison result.

Implementation

 
def <=> other
	if order = self.order
		if other_order = other.order
			if order < other_order
				return -1
			elsif order > other_order
				return 1
			end
		else
			# If we have order, but the other doesn't, we come first:
			return -1
		end
	end
	
	if name = self.name
		if other_name = other.name
			return name <=> other_name
		else
			return -1
		end
	end
	
	return 0
end

def readme_path

The path to the README file for the guide.

Signature
returns　String

The file-system path.

Implementation

 
def readme_path
	Dir[File.expand_path(README, @root)].first
end

def readme?

Does a README file exist for this guide?

Signature
returns　Boolean

Implementation

 
def readme?
	!readme_path.nil?
end

def document

The document for the README, if one exists.

Implementation

 
def document
	if self.readme?
		@document ||= self.readme_document.tap do |document|
			child = document.first_child
			
			if child&.type == :header
				@title = child.first_child.string_content
				
				@description = child.next
				child.delete
			end
		end
	end
end

attr :base

The base instance of the project this example is loaded from.

Signature
attribute　Base

attr :root

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

Signature
attribute　String

def name

The name of the guide.

Signature
returns　String

Implementation

 
def name
	File.basename(@root)
end

def title

The title of the guide.

Signature
returns　String

Implementation

 
def title
	@title || XRB::Strings.to_title(self.name)
end

def href(base = "/")

The hypertext reference to this guide.

Signature
returns　String

Implementation

 
def href(base = "/")
	"#{base}guides/#{self.name}/index"
end

def documentation

The best documentation, extracted from the source files of the guide.

Signature
returns　Decode::Documentation

Implementation

 
def documentation
	@documentation ||= self.best_documentation
end

def navigation

Generate a navigation from the guide's document.

Signature
returns　Sidebar

Implementation

 
def navigation
	@navigation ||= Sidebar.build(self.document)
end

def files

All files associated with this guide.

Signature
returns　Array(String)

The file-system paths.

Implementation

 
def files
	Dir.glob(File.expand_path("*", @root))
end

def sources

All the source files associated with this guide.

Signature
yields　{|source| ...}

If a block is given.

parameter　source　Decode::Source
returns　Enumerator(Decode::Source)

If no block is given.

Implementation

 
def sources
	return to_enum(:sources) unless block_given?
	
	files.each do |path|
		if source = @base.index.languages.source_for(path)
			yield source
		end
	end
end