Class: Utopia::Project::Guide

Inherits:
Object
  • Object
show all
Defined in:
lib/utopia/project/guide.rb

Overview

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

Constant Summary collapse

README = 
"readme.md"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base, root, metadata) ⇒ Guide

Initialize the example with the given root path.



19
20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/utopia/project/guide.rb', line 19

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

Instance Attribute Details

#base ⇒ Object

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



107
108
109
 
# File 'lib/utopia/project/guide.rb', line 107

def base
  @base
end

#description ⇒ Object (readonly)

The description from the first paragraph in the README.



35
36
37
 
# File 'lib/utopia/project/guide.rb', line 35

def description
  @description
end

#metadata ⇒ Object

The metadata associated with the guide.



39
40
41
 
# File 'lib/utopia/project/guide.rb', line 39

def metadata
  @metadata
end

#root ⇒ Object (readonly)

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



111
112
113
 
# File 'lib/utopia/project/guide.rb', line 111

def root
  @root
end

Instance Method Details

#<=>(other) ⇒ Object

Compare guides by explicit order and then by name.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/utopia/project/guide.rb', line 50

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

#document ⇒ Object

The document for the README, if one exists.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/utopia/project/guide.rb', line 90

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

#documentation ⇒ Object

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



133
134
135
 
# File 'lib/utopia/project/guide.rb', line 133

def documentation
	@documentation ||= self.best_documentation
end

#files ⇒ Object

All files associated with this guide.



145
146
147
 
# File 'lib/utopia/project/guide.rb', line 145

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

#href(base = "/") ⇒ Object

The hypertext reference to this guide.



127
128
129
 
# File 'lib/utopia/project/guide.rb', line 127

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

#name ⇒ Object

The name of the guide.



115
116
117
 
# File 'lib/utopia/project/guide.rb', line 115

def name
	File.basename(@root)
end

#navigation ⇒ Object

Generate a navigation from the guide's document.



139
140
141
 
# File 'lib/utopia/project/guide.rb', line 139

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

#order ⇒ Object

The explicit display order of the guide.



43
44
45
 
# File 'lib/utopia/project/guide.rb', line 43

def order
	metadata[:order]
end

#readme? ⇒ Boolean

Does a README file exist for this guide?

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/utopia/project/guide.rb', line 85

def readme?
	!readme_path.nil?
end

#readme_path ⇒ Object

The path to the README file for the guide.



79
80
81
 
# File 'lib/utopia/project/guide.rb', line 79

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

#sources ⇒ Object

All the source files associated with this guide.



153
154
155
156
157
158
159
160
161
 
# File 'lib/utopia/project/guide.rb', line 153

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

#title ⇒ Object

The title of the guide.



121
122
123
 
# File 'lib/utopia/project/guide.rb', line 121

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