Merge pull request #3241 from jekyll/separate-jekyll-docs

bin/jekyll

@@ -6,12 +6,9 @@ $:.unshift File.join(File.dirname(__FILE__), *%w{ .. lib })
 require 'jekyll'
 require 'mercenary'
 
-%w[jekyll-import].each do |blessed_gem|
-  begin
-    require blessed_gem
-  rescue LoadError
-  end
-end
+Jekyll::External.require_if_present(
+  Jekyll::External.blessed_gems
+)
 
 Jekyll::PluginManager.require_from_bundler
 
@@ -32,6 +29,7 @@ Mercenary.program(:jekyll) do |p|
 
   p.action do |args, options|
     if args.empty?
+      Jekyll.logger.error "A subcommand is required."
       puts p
     else
       unless p.has_command?(args.first)

lib/jekyll.rb

@@ -29,12 +29,6 @@ require 'liquid'
 require 'kramdown'
 require 'colorator'
 
-# Conditional optimizations
-begin
-  require 'liquid-c'
-rescue LoadError
-end
-
 SafeYAML::OPTIONS[:suppress_warnings] = true
 Liquid::Template.error_mode = :strict
 
@@ -51,6 +45,7 @@ module Jekyll
   autoload :EntryFilter,         'jekyll/entry_filter'
   autoload :Errors,              'jekyll/errors'
   autoload :Excerpt,             'jekyll/excerpt'
+  autoload :External,            'jekyll/external'
   autoload :Filters,             'jekyll/filters'
   autoload :FrontmatterDefaults, 'jekyll/frontmatter_defaults'
   autoload :Layout,              'jekyll/layout'
@@ -162,6 +157,9 @@ module Jekyll
       end
     end
 
+    # Conditional optimizations
+    Jekyll::External.require_if_present('liquid-c')
+
   end
 end
 
@@ -172,7 +170,7 @@ require_all 'jekyll/generators'
 require_all 'jekyll/tags'
 
 # Eventually remove these for 3.0 as non-core
-Jekyll::Deprecator.gracefully_require(%w[
+Jekyll::External.require_with_graceful_fail(%w[
   toml
   jekyll-paginate
   jekyll-gist

lib/jekyll/commands/build.rb

@@ -66,7 +66,7 @@ module Jekyll
         #
         # Returns nothing.
         def watch(site, options)
-          Deprecator.gracefully_require 'jekyll-watch'
+          External.require_with_graceful_fail 'jekyll-watch'
           Jekyll::Watcher.watch(options)
         end
 

lib/jekyll/commands/docs.rb

@@ -1,30 +0,0 @@
-module Jekyll
-  module Commands
-    class Docs < Command
-
-      class << self
-
-        def init_with_program(prog)
-          prog.command(:docs) do |c|
-            c.syntax 'docs'
-            c.description "Launch local server with docs for Jekyll v#{Jekyll::VERSION}"
-
-            c.option 'port', '-P', '--port [PORT]', 'Port to listen on'
-            c.option 'host', '-H', '--host [HOST]', 'Host to bind to'
-
-            c.action do |args, options|
-              options.merge!({
-                'source'      => File.expand_path("../../../site", File.dirname(__FILE__)),
-                'destination' => File.expand_path("../../../site/_site", File.dirname(__FILE__))
-              })
-              Jekyll::Commands::Build.process(options)
-              Jekyll::Commands::Serve.process(options)
-            end
-          end
-        end
-
-      end
-
-    end
-  end
-end

lib/jekyll/converters/markdown/rdiscount_parser.rb

@@ -3,7 +3,7 @@ module Jekyll
     class Markdown
       class RDiscountParser
         def initialize(config)
-          Jekyll::Deprecator.gracefully_require "rdiscount"
+          Jekyll::External.require_with_graceful_fail "rdiscount"
           @config = config
           @rdiscount_extensions = @config['rdiscount']['extensions'].map { |e| e.to_sym }
         end

lib/jekyll/converters/markdown/redcarpet_parser.rb

@@ -14,7 +14,7 @@ module Jekyll
         module WithPygments
           include CommonMethods
           def block_code(code, lang)
-            Jekyll::Deprecator.gracefully_require("pygments")
+            Jekyll::External.require_with_graceful_fail("pygments")
             lang = lang && lang.split.first || "text"
             add_code_tags(
               Pygments.highlight(code, :lexer => lang, :options => { :encoding => 'utf-8' }),
@@ -55,7 +55,7 @@ module Jekyll
 
 
         def initialize(config)
-          Deprecator.gracefully_require("redcarpet")
+          External.require_with_graceful_fail("redcarpet")
           @config = config
           @redcarpet_extensions = {}
           @config['redcarpet']['extensions'].each { |e| @redcarpet_extensions[e.to_sym] = true }
@@ -71,7 +71,7 @@ module Jekyll
             end
           when "rouge"
             Class.new(Redcarpet::Render::HTML) do
-              Jekyll::Deprecator.gracefully_require(%w[
+              Jekyll::External.require_with_graceful_fail(%w[
                 rouge
                 rouge/plugins/redcarpet
               ])

lib/jekyll/deprecator.rb

@@ -40,22 +40,5 @@ module Jekyll
       Jekyll.logger.warn "Defaults:", "Please update your front-matter defaults to use 'type: #{current}'."
     end
 
-    def gracefully_require(gem_name)
-      Array(gem_name).each do |name|
-        begin
-          require name
-        rescue LoadError => e
-          Jekyll.logger.error "Dependency Error:", <<-MSG
-  Yikes! It looks like you don't have #{name} or one of its dependencies installed.
-  In order to use Jekyll as currently configured, you'll need to install this gem.
-
-  The full error message from Ruby is: '#{e.message}'
-
-  If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/!
-MSG
-          raise Errors::MissingDependencyException.new(name)
-        end
-      end
-    end
   end
 end

lib/jekyll/external.rb

@@ -0,0 +1,59 @@
+module Jekyll
+  module External
+    class << self
+
+      #
+      # Gems that, if installed, should be loaded.
+      # Usually contain subcommands.
+      #
+      def blessed_gems
+        %w{
+          jekyll-docs
+          jekyll-import
+        }
+      end
+
+      #
+      # Require a gem or file if it's present, otherwise silently fail.
+      #
+      # names - a string gem name or array of gem names
+      #
+      def require_if_present(names)
+        Array(names).each do |name|
+          begin
+            require name
+          rescue LoadError
+            Jekyll.logger.debug "Couldn't load #{name}. Skipping."
+            false
+          end
+        end
+      end
+
+      #
+      # Require a gem or gems. If it's not present, show a very nice error
+      # message that explains everything and is much more helpful than the
+      # normal LoadError.
+      #
+      # names - a string gem name or array of gem names
+      #
+      def require_with_graceful_fail(names)
+        Array(names).each do |name|
+          begin
+            require name
+          rescue LoadError => e
+            Jekyll.logger.error "Dependency Error:", <<-MSG
+Yikes! It looks like you don't have #{name} or one of its dependencies installed.
+In order to use Jekyll as currently configured, you'll need to install this gem.
+
+The full error message from Ruby is: '#{e.message}'
+
+If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/!
+            MSG
+            raise Jekyll::Errors::MissingDependencyException.new(name)
+          end
+        end
+      end
+
+    end
+  end
+end

site/_docs/usage.md

@@ -82,3 +82,6 @@ $ jekyll build --source _source --destination _deploy
 
 For more about the possible configuration options, see the
 [configuration](../configuration/) page.
+
+If you're interested in browsing these docs on-the-go, install the
+`jekyll-docs` gem and run `jekyll docs` in your terminal.