module Octopress::Docs

Attributes

docs[R]

Public Class Methods

add(options) click to toggle source

Add doc pages for a plugin

Input: options describing a plugin

Output: array of docs

# 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) click to toggle source

Register a new doc page for a plugin

# 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) click to toggle source
# 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) click to toggle source

Add a single root doc

# 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=[]) click to toggle source

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

# 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) click to toggle source
# 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) click to toggle source
# 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() click to toggle source
# 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?() click to toggle source
# File lib/octopress/docs.rb, line 16
def self.enabled?
  @enabled
end
pages() click to toggle source
# File lib/octopress/docs.rb, line 12
def self.pages
  doc_pages.values.flatten
end
pages_info() click to toggle source

Return a hash of plugin docs information for Jekyll site payload

# 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) click to toggle source
# 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
slug(options) click to toggle source
# 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

Private Class Methods

add_asset_docs(options) click to toggle source

Add doc pages from /asset/docs

# File lib/octopress/docs.rb, line 190
def self.add_asset_docs(options)
  docs = []
  find_doc_pages(options[:docs_path]).each do |doc|
    unless doc =~ /^_/
      opts = options.merge({file: doc, path: options[:docs_path]})   
      docs << add_doc_page(opts)
    end
  end
  docs
end
find_doc_pages(dir) click to toggle source

Find all files in a directory recursively

# File lib/octopress/docs.rb, line 203
def self.find_doc_pages(dir)

  return [] unless Dir.exist? dir

  Find.find(dir).to_a.reject do |f| 
    File.directory? f 
  end.map do |f|
    # truncate file to relative path
    f.sub(dir+'/', '')
  end
end
load_docs(options=nil) click to toggle source
# File lib/octopress/docs.rb, line 219
def self.load_docs(options=nil)
  @enabled = true

  require "octopress-hooks"
  require "octopress/docs/hooks"
  require "octopress/docs/liquid_filters"
  require "octopress/docs/jekyll/convertible"
  require "octopress/docs/jekyll/page"
  require "octopress-escape-code"

  if !options.nil?
    # Look at the local site and require all of its plugins
    # Ensuring their documentation is loaded into the docs site
    #
    site = Octopress.read_site({'config'=>options['config']})

    # Require escape code last to set Octopress hook priority.
    #
    options = Docs.site.config.merge(options)
  end
  options
end
select_first(dir, match) click to toggle source
# File lib/octopress/docs.rb, line 215
def self.select_first(dir, match)
  Dir.new(dir).select { |f| f =~/#{match}/i}.first
end
site(options={}) click to toggle source
# File lib/octopress/docs.rb, line 242
def self.site(options={})
  @site ||= Octopress.site(site_options.merge(options))
end
site_options() click to toggle source
# File lib/octopress/docs.rb, line 246
def self.site_options
  source = Octopress.gem_dir('local')
  {
    'source'      => source,
    'destination' => File.join(source, '_site'),
    'layouts'     => File.join(source, '_layouts'),
    'port'        => '4444',
    'serving'     =>  true,
  }
end