double_doc 2.0.0 → 2.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0b493c229ee510da46837763b4a16a77430c1995
+  data.tar.gz: f2221645c30250b611de735808feaff8901a9439
+SHA512:
+  metadata.gz: 2eb54cc44d17e555cad20baf5c19c329fbef31ed16af3e26a251e91030a7046042fcd72c7029bc132f5d45fcbb726ea93764b348134acd1736bda08bfcd0ba81
+  data.tar.gz: b49bd054fecd71297b57c01deea107f3375be701d411349fa6a106d90cb538c8b008770b4d5397f9c42f690413cd761afd6e5cd2ac7b30cf022e4187ddd4f836

data/lib/double_doc.rb

@@ -1,2 +1,3 @@
 require "double_doc/version"
 require "double_doc/task"
+require "double_doc/client"

data/lib/double_doc/client.rb

@@ -0,0 +1,67 @@
+require 'double_doc/import_handler'
+require 'double_doc/html_generator'
+
+module DoubleDoc
+  class Client
+    attr_reader :md_sources, :options
+
+    def initialize(md_sources, options = {})
+      @md_sources = [md_sources].flatten
+      @options = options
+    end
+
+    def process
+      sources = md_sources.map do |source|
+        if source.to_s =~ /\*/
+          import_handler.load_paths.map do |path|
+            Dir.glob(File.join(path, source))
+          end
+        else
+          import_handler.find_file(source).path
+        end
+      end.flatten.uniq
+
+      generated_md_files = []
+
+      md_dst = Pathname.new(options[:md_destination])
+      system('mkdir', '-p', md_dst.to_s)
+      sources.each do |src|
+        next if File.directory?(src)
+        dst = md_dst + File.basename(src)
+        puts "#{src} -> #{dst}" unless options[:quiet]
+
+        if src.to_s =~ /\.md$/
+          body = import_handler.resolve_imports(File.new(src))
+        else
+          body = File.read(src)
+        end
+
+        File.open(dst, 'w') do |out|
+          out.write(body)
+        end
+
+        generated_md_files << dst
+      end
+
+      args = options[:args] || {}
+      html_dst = Pathname.new(options[:html_destination]) if options[:html_destination]
+      if html_dst || args[:html_destination]
+        html_generator = DoubleDoc::HtmlGenerator.new(generated_md_files, options.merge(args))
+        html_generator.generate
+      end
+
+      sources
+    end
+
+    private
+
+    def import_handler
+      return @import_handler if defined?(@import_handler)
+
+      roots = options[:roots] || [File.dirname(__FILE__)]
+      import_options = options.fetch(:import, {})
+      roots << { :quiet => options[:quiet] }.merge(import_options)
+      @import_handler = DoubleDoc::ImportHandler.new(*roots)
+    end
+  end
+end

data/lib/double_doc/html_generator.rb

@@ -14,6 +14,7 @@ module DoubleDoc
       @html_renderer = options[:html_renderer] || HtmlRenderer
       @stylesheet = options[:html_css] || DEFAULT_CSS
       @title = options[:title] || 'Documentation'
+      @quiet = options[:quiet] == true
       @exclude_from_navigation = options[:exclude_from_navigation] || []
     end
 
@@ -32,7 +33,7 @@ module DoubleDoc
         end
 
         dst = @output_directory + path
-        puts "#{src} -> #{dst}"
+        puts "#{src} -> #{dst}" unless @quiet
         FileUtils.mkdir_p(File.dirname(dst))
 
         if from_markdown

data/lib/double_doc/import_handler.rb

@@ -4,11 +4,14 @@ require 'bundler'
 
 module DoubleDoc
   class ImportHandler
-    attr_reader :root, :load_paths
+    attr_reader :load_paths
 
-    def initialize(root, options = {})
-      @root = Pathname.new(root)
-      @load_paths = [@root]
+    def initialize(*roots)
+      options = roots.pop if roots.last.is_a?(Hash)
+      options ||= {}
+
+      @load_paths = roots.map {|root| Pathname.new(root)}
+      @quiet = options[:quiet] == true
 
       if options[:gemfile]
         begin
@@ -35,6 +38,18 @@ module DoubleDoc
       end
     end
 
+    def find_file(path)
+      load_path = @load_paths.detect do |load_path|
+        (load_path + path).exist?
+      end
+
+      unless load_path
+        raise LoadError, "No such file or directory: #{path}"
+      end
+
+      File.new(load_path + path)
+    end
+
     protected
 
     def load_paths_from_gemfile(root)
@@ -45,7 +60,7 @@ module DoubleDoc
       end
 
       with_gemfile(gemfile) do
-        puts "Loading paths from #{gemfile}"
+        puts "Loading paths from #{gemfile}" unless @quiet
 
         defn = Bundler::Definition.build(gemfile, root + "Gemfile.lock", nil)
         defn.validate_ruby!
@@ -83,18 +98,6 @@ module DoubleDoc
       end
     end
 
-    def find_file(path)
-      load_path = @load_paths.detect do |load_path|
-        (load_path + path).exist?
-      end
-
-      unless load_path
-        raise LoadError, "No such file or directory: #{path}"
-      end
-
-      File.new(load_path + path)
-    end
-
     def with_gemfile(gemfile)
       ENV["BUNDLE_GEMFILE"], orig_gemfile = gemfile.to_s, ENV["BUNDLE_GEMFILE"]
       yield

data/lib/double_doc/task.rb

@@ -1,19 +1,19 @@
 require 'rake'
 require 'pathname'
 require 'tmpdir'
-require 'double_doc/import_handler'
-require 'double_doc/html_generator'
+require 'double_doc/client'
 
 module DoubleDoc
 
   ## ### Rake Task
   ## It is very easy to set up a rake task for generating your documentation. All you have to do is
-  ## tell DoubleDoc what the input files are, and where you want the output to go.
+  ## tell DoubleDoc what the input files are, and where you want the output to go. In the example,
+  ## `double_doc` is picked to avoid conflicts with the `doc` rake task in rails.
   ##
   ## ```ruby
   ## require 'double_doc'
   ##
-  ## DoubleDoc::Task.new(:doc,
+  ## DoubleDoc::Task.new(:double_doc,
   ##   :sources          => 'doc/source/*.md',
   ##   :md_destination   => 'doc/generated',
   ##   :html_destination => 'site'
@@ -32,14 +32,15 @@ module DoubleDoc
   ## | __html_css__         | You can use your own custom CSS document by specifying it's path here.
   ## | __title__            | The title you want in the generated HTML. Defaults to "Documentation".
   ##
-  ## If you just want to use double doc to generate your README.md for github, you should write your documentation in doc/README.md and put his in your Rakefile:
+  ## If you just want to use double_doc to generate your README.md for github, you should write your documentation in doc/README.md and put this in your Rakefile:
   ##
   ## ```ruby
   ## require 'double_doc'
   ##
-  ## DoubleDoc::Task.new(:doc, :sources => 'doc/README.md', :md_destination => '.')
+  ## DoubleDoc::Task.new(:double_doc, :sources => 'doc/README.md', :md_destination => '.')
   ## ```
-  ## Then all you have to do is to run `rake doc`, and you will have a `readme.md` in the root of your project.
+  ##
+  ## Then all you have to do is to run `rake double_doc`, and you will have a `readme.md` in the root of your project.
   ##
   ## If you have a gh-pages branch set up in your repository, you can event run `rake doc:publish` to generate html documentation and push it to your github pages.
   class Task
@@ -48,41 +49,20 @@ module DoubleDoc
     def initialize(task_name, options)
       md_dst   = Pathname.new(options[:md_destination])
       html_dst = Pathname.new(options[:html_destination]) if options[:html_destination]
-      sources  = FileList[*options[:sources]].uniq
 
       destinations = [md_dst, html_dst].compact
       destinations.each do |dst|
         directory(dst.to_s)
       end
 
-      desc "Generate markdown #{html_dst ? 'and HTML ' : ''}DoubleDoc documentation from #{sources.join(', ')}"
-      generated_task = task(task_name => destinations) do |t, args|
-        import_handler = DoubleDoc::ImportHandler.new(options[:root] || Rake.original_dir, options.fetch(:import, {}))
-
-        generated_md_files = []
-
-        sources.each do |src|
-          dst = md_dst + File.basename(src)
-          puts "#{src} -> #{dst}"
-
-          if src.to_s =~ /\.md$/
-            body = import_handler.resolve_imports(File.new(src))
-          else
-            body = File.new(src).read
-          end
-
-          File.open(dst, 'w') do |out|
-            out.write(body)
-          end
-
-          generated_md_files << dst
-        end
-
-        if html_dst || args[:html_destination]
-          html_generator = DoubleDoc::HtmlGenerator.new(generated_md_files, options.merge(args))
-          html_generator.generate
-        end
+      roots = Array(options[:root])
+      roots << Rake.original_dir if roots.empty?
 
+      desc "Generate markdown #{html_dst ? 'and HTML ' : ''}DoubleDoc documentation"
+      generated_task = task(task_name => destinations) do |t, args|
+        opts = args.merge(options.merge(:roots => roots))
+        client = DoubleDoc::Client.new(options[:sources], opts)
+        client.process
       end
 
       has_github_pages = !`git branch | grep 'gh-pages'`.empty? rescue false

data/lib/double_doc/version.rb

@@ -1,4 +1,4 @@
 ## ## DoubleDoc 2.0
 module DoubleDoc
-  VERSION = "2.0.0"
+  VERSION = "2.0.1"
 end

data/readme.md

@@ -1,4 +1,7 @@
-## DoubleDoc 1.3
+## DoubleDoc 2.0
+
+[![Build Status](https://travis-ci.org/zendesk/double_doc.svg?branch=master)](https://travis-ci.org/zendesk/double_doc)
+
 
 One of the challenges you face when writing public documention for code or APIs, is that you have to remember to update the documentation
 when ever you change the API. The main reason why this is a problem is that very often the documentation lives very for from your code.
@@ -66,12 +69,13 @@ And DoubleDoc will generate this markdown document for you:
 
 ### Rake Task
 It is very easy to set up a rake task for generating your documentation. All you have to do is
-tell DoubleDoc what the input files are, and where you want the output to go.
+tell DoubleDoc what the input files are, and where you want the output to go. In the example,
+`double_doc` is picked to avoid conflicts with the `doc` rake task in rails.
 
 ```ruby
 require 'double_doc'
 
-DoubleDoc::Task.new(:doc,
+DoubleDoc::Task.new(:double_doc,
   :sources          => 'doc/source/*.md',
   :md_destination   => 'doc/generated',
   :html_destination => 'site'
@@ -90,21 +94,20 @@ The available options are:
 | __html_css__         | You can use your own custom CSS document by specifying it's path here.
 | __title__            | The title you want in the generated HTML. Defaults to "Documentation".
 
-If you just want to use double doc to generate your README.md for github, you should write your documentation in doc/README.md and put his in your Rakefile:
+If you just want to use double_doc to generate your README.md for github, you should write your documentation in doc/README.md and put this in your Rakefile:
 
 ```ruby
 require 'double_doc'
 
-DoubleDoc::Task.new(:doc, :sources => 'doc/README.md', :md_destination => '.')
+DoubleDoc::Task.new(:double_doc, :sources => 'doc/README.md', :md_destination => '.')
 ```
-Then all you have to do is to run `rake doc`, and you will have a `readme.md` in the root of your project.
+
+Then all you have to do is to run `rake double_doc`, and you will have a `readme.md` in the root of your project.
 
 If you have a gh-pages branch set up in your repository, you can event run `rake doc:publish` to generate html documentation and push it to your github pages.
 
 ### Notes
-DoubleDoc is tested as working on both ruby 1.8.7 and 1.9.3, but does not work on jruby because if it's dependency on redcarpet.
-
-[![Build Status](https://secure.travis-ci.org/staugaard/double_doc.png?branch=master)](http://travis-ci.org/staugaard/double_doc)
+DoubleDoc is tested as working on both ruby 1.8.7 and 1.9.3, but does not work on jruby because of its dependency on redcarpet.
 
 ### TODO
 * Tests

data/test/client_test.rb

@@ -0,0 +1,51 @@
+require 'test_helper'
+
+describe "import handler" do
+  subject do
+    DoubleDoc::Client.new(sources, options)
+  end
+
+  describe '#process' do
+    let(:destination) { Dir.mktmpdir }
+    let(:sources) { [Bundler.root + 'doc/readme.md'] }
+    let(:options) { { :md_destination => destination, :roots => [Bundler.root], :quiet => true } }
+
+    before do
+      subject.process
+    end
+
+    it 'produces output at the md_destination' do
+      File.exists?(destination + '/readme.md').must_equal true
+    end
+
+    describe 'with a missing directory' do
+      let(:destination) { Dir.mktmpdir + '/tmp' }
+
+      it 'creates the directory' do
+        File.exists?(destination + '/readme.md').must_equal true
+      end
+    end
+
+    describe 'with multiple sources' do
+      let(:sources) { %w(readme todo).map{|f| Bundler.root + "doc/#{f}.md" } }
+
+      it 'processes all sources' do
+        File.exists?(destination + '/readme.md').must_equal true
+        File.exists?(destination + '/todo.md').must_equal true
+      end
+    end
+
+    describe 'producing html' do
+      let(:options) { {
+        :md_destination => destination,
+        :html_destination => destination + '/html',
+        :roots => [Bundler.root],
+        :quiet => true
+      } }
+
+      it 'creates html files' do
+        File.exists?(destination + '/html/readme.html').must_equal true
+      end
+    end
+  end
+end

data/test/html_generator_test.rb

@@ -10,7 +10,10 @@ describe "the html generator" do
     @output_file_name = @destination + 'input.html'
     Dir.mkdir(@root + 'source')
     Dir.mkdir(@destination)
-    @generator = DoubleDoc::HtmlGenerator.new([@input_file_name], { :html_destination => @destination })
+    @generator = DoubleDoc::HtmlGenerator.new([@input_file_name], {
+      :html_destination => @destination,
+      :quiet => true
+    })
   end
 
   after do
@@ -63,7 +66,8 @@ describe "the html generator" do
 
     it "should generate links for each page in the navigation area" do
       generator = DoubleDoc::HtmlGenerator.new(@input_files, {
-        :html_destination => @destination
+        :html_destination => @destination,
+        :quiet => true
       })
       generator.generate
 
@@ -76,7 +80,8 @@ describe "the html generator" do
     it "should skip specified filed" do
       generator = DoubleDoc::HtmlGenerator.new(@input_files, {
         :html_destination => @destination,
-        :exclude_from_navigation => ['file_two.html']
+        :exclude_from_navigation => ['file_two.html'],
+        :quiet => true
       })
       generator.generate
 

data/test/import_handler_test.rb

@@ -2,13 +2,24 @@ require 'test_helper'
 
 describe "import handler" do
   subject do
-    DoubleDoc::ImportHandler.new(root, options)
+    roots = Array(root).push(options.merge( :quiet => true ))
+    DoubleDoc::ImportHandler.new(*roots)
   end
 
   after do
     ENV["BUNDLE_GEMFILE"] = Bundler.root.join("Gemfile").to_s
   end
 
+  describe "multiple roots" do
+    let(:root) { [Bundler.root + 'lib', Bundler.root + 'doc'] }
+    let(:options) {{}}
+
+    it "finds files from either root" do
+      subject.find_file("double_doc.rb").must_be_instance_of File
+      subject.find_file("readme.md").must_be_instance_of File
+    end
+  end
+
   describe "with gemfile" do
     let(:root) { Bundler.root }
     let(:options) {{ :gemfile => true }}
@@ -16,19 +27,19 @@ describe "import handler" do
     describe "rubygems" do
       describe "load_paths" do
         it "should add Gemfile load paths" do
-          subject.load_paths.must_include subject.root
+          subject.load_paths.must_include root
           subject.load_paths.size.must_be :>, 1
         end
       end
 
       describe "find_file" do
         it "should resolve files" do
-          subject.send(:find_file, "bundler.rb").must_be_instance_of File
+          subject.find_file("bundler.rb").must_be_instance_of File
         end
 
         it "should raise if unable to find file" do
           lambda do
-            subject.send(:find_file, "nope.rb")
+            subject.find_file("nope.rb")
           end.must_raise LoadError
         end
       end
@@ -36,11 +47,11 @@ describe "import handler" do
 
     describe "find_file" do
       it "should resolve files from path" do
-        subject.send(:find_file, "double_doc.rb").must_be_instance_of File
+        subject.find_file("double_doc.rb").must_be_instance_of File
       end
 
       it "should resolve file from git" do
-        subject.send(:find_file, "mime-types.rb").must_be_instance_of File
+        subject.find_file("mime-types.rb").must_be_instance_of File
       end
     end
   end

metadata

@@ -1,110 +1,97 @@
 --- !ruby/object:Gem::Specification
 name: double_doc
 version: !ruby/object:Gem::Version
-  version: 2.0.0
-  prerelease: 
+  version: 2.0.1
 platform: ruby
 authors:
 - Mick Staugaard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-15 00:00:00.000000000 Z
+date: 2015-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: erubis
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: pygments.rb
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
 description: A simple framework for writing and generating beautiful documentation
@@ -115,53 +102,49 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/double_doc.rb
+- lib/double_doc/client.rb
 - lib/double_doc/doc_extractor.rb
 - lib/double_doc/html_generator.rb
 - lib/double_doc/html_renderer.rb
 - lib/double_doc/import_handler.rb
 - lib/double_doc/task.rb
 - lib/double_doc/version.rb
-- lib/double_doc.rb
 - lib/guard/double_doc.rb
 - lib/guard/doubledoc.rb
+- readme.md
 - templates/default.html.erb
 - templates/screen.css
-- readme.md
+- test/client_test.rb
 - test/doc_extractor_test.rb
 - test/html_generator_test.rb
 - test/import_handler_test.rb
 - test/test_helper.rb
 homepage: http://staugaard.github.com/double_doc
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -1964755725115919551
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -1964755725115919551
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.4.5
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Documentation right where you want it
 test_files:
+- test/client_test.rb
 - test/doc_extractor_test.rb
 - test/html_generator_test.rb
 - test/import_handler_test.rb