Module: Octopress::Docs

Defined in:
lib/octopress/docs.rb,
lib/octopress/docs/doc.rb,
lib/octopress/docs/hooks.rb,
lib/octopress/commands/docs.rb,
lib/octopress/docs/jekyll/page.rb,
lib/octopress/docs/jekyll/convertible.rb

Defined Under Namespace

Modules: Convertible Classes: Commands, Doc, DocsSiteHook, Page

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#docs ⇒ Object (readonly)

Returns the value of attribute docs.



6
7
8
 
# File 'lib/octopress/docs.rb', line 6

def docs
  @docs
end

Class Method Details

.add(options) ⇒ Object

Add doc pages for a plugin

Input: options describing a plugin

Output: array of docs



143
144
145
146
147
148
149
 
# File 'lib/octopress/docs.rb', line 143

def self.add(options)
  options = default_options(options)
  docs = []
  docs.concat add_asset_docs(options)
  docs.concat add_root_docs(options, docs)
  docs.compact! 
end

.add_doc_page(options) ⇒ Object

Register a new doc page for a plugin



179
180
181
182
183
184
 
# File 'lib/octopress/docs.rb', line 179

def self.add_doc_page(options)
  page = Docs::Doc.new(options)
  @docs[options[:slug]] ||= []
  @docs[options[:slug]] << page
  page
end

.add_plugin_docs(plugin) ⇒ Object 



82
83
84
85
86
87
88
89
 
# File 'lib/octopress/docs.rb', line 82

def self.add_plugin_docs(plugin)
  options = plugin_options(plugin)
  options[:docs] ||= %w{readme docs}

  plugin_doc_pages = add_asset_docs(options)
  plugin_doc_pages.concat add_root_docs(options, plugin_doc_pages)
  plugin_doc_pages
end

.add_root_doc(filename, options) ⇒ Object

Add a single root doc



171
172
173
174
175
 
# File 'lib/octopress/docs.rb', line 171

def self.add_root_doc(filename, options)
  if file = select_first(options[:path], filename)
    add_doc_page(options.merge({file: file}))
  end
end

.add_root_docs(options, asset_docs = []) ⇒ Object

Add pages from the root of a gem (README, CHANGELOG, etc)



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/octopress/docs.rb', line 153

def self.add_root_docs(options, asset_docs=[])
  root_docs = []
  options[:docs].each do |doc|
    doc_data = {
      'title' => doc.capitalize
    }

    if doc =~ /readme/ && asset_docs.select {|d| d.file =~ /^index/ }.empty?
      doc_data['permalink'] = '/'
    end

    root_docs << add_root_doc(doc, options.merge(data: doc_data))
  end
  root_docs
end

.base_url(options) ⇒ Object 



125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/octopress/docs.rb', line 125

def self.base_url(options)
  options[:base_url] || if options[:type] == 'theme'
    'theme'
  else
    if options[:source_url] =~ /github\.com\/(octopress|imathis)/
      File.join('octopress', options[:slug].sub(/octopress-/,''))
    else
      File.join('plugins', options[:slug])
    end
  end
end

.default_options(options) ⇒ Object 



110
111
112
113
114
115
116
117
118
 
# File 'lib/octopress/docs.rb', line 110

def self.default_options(options)
  options[:docs] ||= %w{readme changelog}
  options[:type] ||= 'plugin'
  options[:slug] = slug(options)
  options[:base_url] = base_url(options)
  options[:path] ||= '.'
  options[:docs_path] ||= File.join(options[:path], 'assets', 'docs')
  options
end

.doc_pages ⇒ Object 



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/octopress/docs.rb', line 20

def self.doc_pages
  if !@pages
    @pages = @docs.dup

    @pages.each do |slug, docs|

      # Convert docs to pages
      #
      docs.map! { |doc| doc.page }

      # Inject docs links from other docs pages
      #
      docs.map! do |doc|
        doc.data = doc.data.merge({
          'docs' => plugin_page_links(@pages[slug])
        })
        doc
      end
    end
  end
  @pages
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


16
17
18
 
# File 'lib/octopress/docs.rb', line 16

def self.enabled?
  @enabled
end

.pages ⇒ Object 



12
13
14
 
# File 'lib/octopress/docs.rb', line 12

def self.pages
  doc_pages.values.flatten
end

.pages_info ⇒ Object

Return a hash of plugin docs information for Jekyll site payload



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/octopress/docs.rb', line 63

def self.pages_info
  docs = {}

  # Retrieve plugin info from docs
  #
  doc_pages.each do |slug, pages|
    data = pages.first.data
    docs[slug] = data['plugin'].merge({
      'pages' => data['docs']
    })
  end

  # Sort docs alphabetically by name
  #
  docs = Hash[docs.sort_by { |k,v| v['name'] }]

  @pages_info = { 'plugin_docs' => docs }
end

.plugin_options(plugin) ⇒ Object 



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/octopress/docs.rb', line 91

def self.plugin_options(plugin)
  options = {
    name: plugin.name,
    slug: plugin.slug,
    type: plugin.type,
    version: plugin.version,
    gem: plugin.gem,
    description: plugin.description,
    path: plugin.path,
    source_url: plugin.source_url,
    website: plugin.website,
    docs_path: File.join(plugin.assets_path, 'docs'),
    docs: %w{readme changelog}
  }

  options[:base_url] = base_url(options)
  options
end

.plugin_page_links(pages) ⇒ Object 



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/octopress/docs.rb', line 43

def self.plugin_page_links(pages)
  pages.clone.map { |page|
    data = page.data
    title   = data['link_title'] || data['title'] || page.basename
    url = File.join('/', data['plugin']['url'], page.url.sub('index.html', ''))

    {
      'title' => title,
      'url' => url
    }
  }.sort_by { |i| 
    # Sort by depth of url
    i['url'].split('/').size
  }
end

.slug(options) ⇒ Object 



120
121
122
123
 
# File 'lib/octopress/docs.rb', line 120

def self.slug(options)
  slug = options[:slug] || options[:name]
  options[:type] == 'theme' ? 'theme' : Jekyll::Utils.slugify(slug)
end