octopress 3.0.0.rc.23 → 3.0.0.rc.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6e523447917ea22e1ab48694250218ccd5f33a4a
-  data.tar.gz: 8e6e25505a1162bed932bc5b27fb37d9bd81600d
+  metadata.gz: 80b8a068d4811564da346c04165ff5958a72545b
+  data.tar.gz: 38db301d32c4ab9eebcfc5a4ad9ea9df4e5bb08a
 SHA512:
-  metadata.gz: 01a45cfc7ee54255478289f8e21a29bf888d8a59aa9f7df25fb2d5a937c7998cb7fa2b466c57826b4e75ac62d10dc2a96023d052f7e5434f616b8ec6f2713518
-  data.tar.gz: f97fb94fc513b972c6ee6c170dcdcb659c123c6b75b9474c20075e6f3f3c2364e8d19dd51ef0dd8616903760691622a2aa69eef4508925f5f88e74a8fd2094b7
+  metadata.gz: bc120b3c743aa1d11bc6ab6f553f6a4c08f7b295a983560c609439119d162a9f86f45a4c9981d5608da0dc76f536b4cbebfb1732950dae9fa93444f521e10c1e
+  data.tar.gz: 060dfc709a8f52b7fb910d3a3ff194490b64bd67a16820432fc43f2b99ebd421c820a5b61a0f28799c560b864bb2390388badd171de94fbeed37fd116cdcf53f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Octopress Changelog
 
+### 3.0.0 RC24 - 2015-01-02
+
+- Absorbed Octopress Docs features
+
 ### 3.0.0 RC23 - 2014-12-19
 
 - Fixed issue with site configuration caching

data/assets/docs/docs.md

@@ -0,0 +1,28 @@
+---
+title: Documentation Plugins
+permalink: /docs/
+---
+
+# Octopress Docs
+
+If you have the Octopress gem installed, run `$ octopress docs` from the root of your Jekyll site, and a website will mount at `http://localhost:4444` with documentation for Octopress and any plugins which support this feature.
+
+## Adding docs to your plugin
+
+If your plugin is built on Octopress Ink, these documentation pages are added automatically. If not, use
+the code below to automatically add your plugin's Readme, Changelog and any pages in your gem path under `assets/docs`.
+
+```ruby
+if defined? Octopress::Docs
+  Octopress::Docs.add({
+    name:        "Your Plugin",
+    description: "This plugin causes awesomeness",
+    path:        File.expand_path(File.join(File.dirname(__FILE__), "../")), # gem root
+    slug:        "your-plugin",                      # optional
+    source_url:  "https://github.com/some/project",  # optional
+    website:     "http://example.com",               # optional
+  })
+end
+```
+
+It's a bit odd, but the `if defined? Octopress::Docs` allows you to register doc pages if possible, without having to add the octopress gem as a dependency.

data/lib/octopress.rb

@@ -5,11 +5,12 @@ module Octopress
   require 'octopress/command'
   require 'octopress/version'
   require 'octopress/commands/new'
+  require 'octopress/commands/docs'
   require 'octopress/commands/init'
   require 'octopress/commands/publish'
   require 'octopress/commands/isolate'
   require 'octopress/isolate'
-  require 'octopress-docs'
+  require 'octopress/docs'
 
   autoload :Page, 'octopress/page'
   autoload :Post, 'octopress/post'

data/lib/octopress/commands/docs.rb

@@ -0,0 +1,41 @@
+module Octopress
+  module Docs
+    class Commands < Octopress::Command
+      def self.init_with_program(p)
+        p.command(:docs) do |c|
+          c.syntax 'octopress docs'
+          c.description "Launch local server with docs for Octopress v#{Octopress::VERSION} and Octopress plugins."
+
+          c.option 'port', '-P', '--port [PORT]', 'Port to listen on'
+          c.option 'host', '-H', '--host [HOST]', 'Host to bind to'
+          if ENV['OCTODEV']
+            c.option 'watch', '--watch', 'Watch docs site for changes and rebuild. (For docs development)'
+          end
+
+          c.action do |args, options|
+            serve_docs(options)
+          end
+        end
+      end
+
+      def self.serve_docs(options)
+
+        # Activate dependencies for serving docs.
+        #
+        options = Docs.load_docs(options)
+        Octopress::Ink.load_plugin_assets = false
+
+        
+        Jekyll.logger.log_level = :error
+        Jekyll::Commands::Build.process(options)
+        url = "http://#{options['host']}:#{options['port']}"
+        puts "Serving Docs site: #{url}"
+        puts "  press ctrl-c to stop."
+        Jekyll::Commands::Serve.process(options)
+        Jekyll.logger.log_level = :info
+      end
+
+    end
+  end
+end
+

data/lib/octopress/docs.rb

@@ -0,0 +1,256 @@
+require "find"
+require "octopress/docs/doc"
+
+module Octopress
+  module Docs
+    attr_reader :docs
+    @docs = {}
+    @enabled = false
+
+    autoload :Doc, 'octopress/docs/doc'
+
+    def self.pages
+      doc_pages.values.flatten
+    end
+
+    def self.enabled?
+      @enabled
+    end
+
+    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
+
+    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
+    
+
+    # Return a hash of plugin docs information
+    # for Jekyll site payload
+    #
+    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
+
+    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
+
+    def self.plugin_options(plugin)
+      options = {
+        name: plugin.name,
+        slug: plugin.slug,
+        type: plugin.type,
+        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
+
+    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
+
+    def self.slug(options)
+      slug = options[:slug] || options[:name]
+      options[:type] == 'theme' ? 'theme' : Jekyll::Utils.slugify(slug)
+    end
+    
+    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
+
+    # Add doc pages for a plugin
+    # 
+    # Input: options describing a plugin
+    #
+    # Output: array of docs
+    #
+    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 pages from the root of a gem (README, CHANGELOG, etc)
+    #
+    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
+
+    # Add a single root doc
+    #
+    def self.add_root_doc(filename, options)
+      if file = select_first(options[:path], filename)
+        add_doc_page(options.merge({file: file}))
+      end
+    end
+
+    # Register a new doc page for a plugin
+    #
+    def self.add_doc_page(options)
+      page = Docs::Doc.new(options)
+      @docs[options[:slug]] ||= []
+      @docs[options[:slug]] << page
+      page
+    end
+
+    private
+
+    # Add doc pages from /asset/docs
+    #
+    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 all files in a directory recursively
+    #
+    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
+
+    def self.select_first(dir, match)
+      Dir.new(dir).select { |f| f =~/#{match}/i}.first
+    end
+
+    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"
+
+      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']})
+        site.plugin_manager.conscientious_require
+
+        # Require escape code last to set Octopress hook priority.
+        #
+        options = Docs.site.config.merge(options)
+      end
+
+      require "octopress-escape-code"
+      options
+    end
+
+    def self.site(options={})
+      @site ||= Octopress.site(site_options.merge(options))
+    end
+
+    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
+  end
+end

data/lib/octopress/docs/doc.rb

@@ -0,0 +1,91 @@
+module Octopress
+  module Docs
+    class Doc
+      attr_reader :filename, :plugin_name, :plugin_slug, :base_url, :plugin_type, :description, :source_url
+
+      def initialize(options={})
+        @file            = options[:file]
+        @path            = options[:path] ||= '.'
+        @file_dir        = File.dirname(@file)
+        @plugin_name     = options[:name]
+        @plugin_slug     = options[:slug]
+        @plugin_type     = options[:type]
+        @base_url        = options[:base_url]
+        @source_url      = options[:source_url]
+        @description     = options[:description]
+        @data            = options[:data] || {}
+      end
+
+      # Add doc page to Jekyll pages
+      #
+      def add
+        Octopress.site.pages << page
+      end
+
+      def disabled?
+        false
+      end
+
+      def file
+        File.basename(@file)
+      end
+
+      def info
+        "  - #{permalink.ljust(35)}"
+      end
+
+      def page
+        @page ||= begin
+          p = Octopress::Docs::Page.new(Octopress.site, @path, page_dir, file, {'path'=>@base_url})
+          p.data['layout'] = 'docs'
+          p.data['escape_code'] = true
+
+          p.data['plugin'] = { 
+            'name'        => @plugin_name, 
+            'slug'        => @plugin_slug,
+            'type'        => @plugin_type,
+            'source_url'  => @source_url,
+            'description' => @description,
+            'url'         => @base_url
+          }
+
+          p.data['dir'] = doc_dir
+          p.data = @data.merge(p.data)
+          p.data.merge!(comment_yaml(p.content))
+          p
+        end
+      end
+
+      private
+
+      def permalink
+        File.basename(file, ".*")
+      end
+
+      def read
+        File.open(File.join(@path, @file)).read
+      end
+
+      def plugin_slug
+        Jekyll::Utils.slugify(@plugin_type == 'theme' ? 'theme' : @plugin_slug)
+      end
+
+      def page_dir
+        @file_dir == '.' ? '' : @file_dir
+      end
+
+      def doc_dir
+        File.join(@path, page_dir, File.dirname(@file))
+      end
+
+      def comment_yaml(content)
+        if content =~ /<!-{3}\s+(.+)?-{3}>/m
+          SafeYAML.load($1)
+        else
+          {}
+        end
+      end
+    end
+  end
+end
+