docs 0.0.4 → 0.0.5

data/README.mdown

@@ -1,5 +1,5 @@
 # Docs
-Docs is a documentation generator for Ruby. It is intended for documenting things like HTTP APIs where the documentation doesn't make sense in the code.
+Docs is a documentation generator for Ruby. It is intended for documenting things like HTTP APIs where the documentation doesn't make sense within the code.
 
 ## Install
 
@@ -23,25 +23,45 @@ It will create the following file structure:
 
 The `docs` directory contains your documentation (written in Markdown, using the `.mdown` file extension), these are compiled to HTML at build time. The Markdown files are pre-processed with ERB, primarily so you can include your examples (up next).
 
-The `examples` directory contains the examples used within your code. They are stored as shell scripts written in either BASH or Ruby. Both the source of these files and the output when run is made available to your documentation files at build time. These are stored outside of the actual documentation so you can write tests for them. To include the source of an example named `examples/create_a_user.sh`:
+The `examples` directory contains the examples used within your code. The source of these files is made available to all documentation files at build time. If the files are written in either BASH or Ruby, using the `.sh` and `.rb` extensions, respesctively, the output of these scripts when run is also made available. These are stored outside of the actual documentation so you can test them (ensuring you don't ship bad docs!). 
+
+You can specify that an example is preprocessed with ERB by prefixing its actual file extension with `.erb`. e.g. `examples/create_a_user.sh` would become `examples/create_a_user.erb.sh`. This is useful for including config variables set in `config.yaml` (see below).
+
+To include the source of an example named `examples/create_a_user.sh`:
 
 ```erb
 <%= examples :source, 'examples/create_a_user.sh' %>
 ```
 
-If you would like to show in your documentation the output of the bash script:
+If you would like to show the output:
 
 ```erb
 <%= examples :output, 'examples/create_a_user.sh' %>
 ```
 
-The `config.yaml` file contains some config variables for Docs. Any variable set here is accessible within your documentation:
+The `config.yaml` file contains some config variables for Docs. Any variable set here is accessible within your documentation and within examples pre-processed with ERB:
 
 ```erb
 <%= config.template %>
 ```
 
-If `template` is set in `config.yaml`, all markdown files will be compiled with `template` used as the template. Within template you can include the compiled Markdown:
+`config.yaml` also supports environment dependent variables. These are useful for setting things like your API endpoint, so you can compile the docs locally or against production. e.g.
+
+```yaml
+environment:
+  production:
+    api_endpoint: "http://api.intercom.io/"
+  development:
+    api_endpoint: "http://intercom.dev"
+```
+
+The default environment is `production`, to change the environment set the value of the `DOCS_ENV` environment variable. In the example above if docs was run in the `production` environment, `api_endpoint` would be set as a top level attribute in `config` and the variables set in `development` would be inaccessible. e.g.
+
+```erb
+<%= config.api_endpoint %>
+```
+
+If `template` is set in `config.yaml`, all markdown files will be compiled with `template` used as the template. Within the template you can include the compiled Markdown:
 
 ```erb
 <%= content %>

data/bin/docs

@@ -1,3 +1,9 @@
 #!/usr/bin/env ruby
-require 'docs'
+unless ENV['DOCS_DEV']
+  require 'docs'
+else
+  $:.unshift(f = File.join(File.dirname(__FILE__), '../lib'))
+  require "#{f}/docs"
+end
+
 Docs::Project.start

data/lib/docs.rb

@@ -5,3 +5,6 @@ require "docs/version"
 require "docs/project"
 require "docs/config"
 require "docs/erb_environment"
+require "docs/example"
+require 'docs/example/helper'
+require "docs/erb_renderer"

data/lib/docs/config.rb

@@ -2,7 +2,7 @@ require 'yaml'
 
 module Docs
   class Config
-    def initialize(config_file)
+    def initialize(config_file = 'config.yaml')
       @config = YAML.load(File.read(config_file))
       @environment = ENV['DOCS_ENV'] || 'production'
 

data/lib/docs/erb_environment.rb

@@ -1,17 +1,15 @@
 require 'coderay'
 require 'json'
 
+require 'docs/example/helper'
+
 module Docs
   class ERBEnvironment
     attr_writer :examples
     attr_accessor :content
     attr_accessor :config # <%= config.api_endpoint %> 
 
-    # <%= example :source, "curl/users/getting.sh" %>
-    def example(source_or_output, name)
-      raise ArgumentError, "Must specify :source or :output as first argument" unless [:source, :output].include?(source_or_output) 
-      @examples[source_or_output]["examples/#{name}"]
-    end
+    include ExampleHelper
 
     def pretty_print_json(json)
       begin

data/lib/docs/erb_renderer.rb

@@ -0,0 +1,15 @@
+require 'erb'
+
+module Docs
+  class ERBRenderer
+
+    def initialize(erb_environment)
+      @erb_environment = erb_environment
+    end
+
+    def render(str)
+      ERB.new(str).result(@erb_environment.get_binding)
+    end
+
+  end
+end

data/lib/docs/example.rb

@@ -0,0 +1,59 @@
+require 'docs/config'
+require 'docs/erb_environment'
+require 'docs/example/helper'
+
+module Docs
+  class Example
+    EXTENSIONS_TO_COMMANDS = {
+      '.sh' => 'bash',
+      '.rb' => 'ruby'
+    }
+
+    def initialize(example_name, erb_renderer=nil)
+      @config = Config.new
+      @erb = erb_renderer || new_erb_renderer 
+
+      @source = nil
+      @output = nil
+
+      @file_name = example_name
+      @rendered_file_name = nil
+    end
+
+    def output
+      return @output if @output
+
+      source if (is_erb? && !@rendered_file_name)
+
+      file_name = @rendered_file_name || @file_name
+      i = IO.popen("#{EXTENSIONS_TO_COMMANDS[File.extname(file_name)]} #{file_name}")
+
+      @output = i.read
+    end
+
+    def source
+      @source ||= (is_erb?) ? render_erb_template : File.read(@file_name)
+    end
+
+    def is_erb?
+      @is_erb ||= File.fnmatch?('*.erb.*', @file_name)
+    end
+
+    private
+    def new_erb_renderer
+      erb_environment = ERBEnvironment.new
+      erb_environment.config = Config.new
+      ERBRenderer.new erb_environment
+    end
+
+    def render_erb_template
+      rendered = @erb.render(File.read(@file_name))
+
+      File.open(@rendered_file_name = "#{@config.directories['temp']}/#{Digest::MD5.hexdigest(@file_name)}#{File.extname(@file_name)}", 'w+') do |f|
+        f.write rendered 
+      end
+
+      rendered
+    end
+  end
+end

data/lib/docs/example/helper.rb

@@ -0,0 +1,15 @@
+module Docs
+  module ExampleHelper
+    def examples(examples_path, erb_renderer)
+      Dir.glob(examples_path).inject({}) do |hsh, example_name|
+        hsh[example_name] = Example.new(example_name, erb_renderer)
+        hsh
+      end
+    end
+
+    def example(source_or_output, name)
+      raise ArgumentError, "Must specify :source or :output as first argument" unless [:source, :output].include?(source_or_output) 
+      @examples["examples/#{name}"].send(source_or_output)
+    end
+  end
+end

data/lib/docs/project.rb

@@ -1,18 +1,15 @@
 require 'fileutils'
 require 'digest/md5'
-
 require 'erb'
+
 require 'redcarpet'
+require 'docs/example/helper'
 
 module Docs
   class Project < Thor
 
     include Thor::Actions
-
-    EXTENSIONS_TO_COMMANDS = {
-      '.sh' => 'bash',
-      '.rb' => 'ruby'
-    }
+    include ExampleHelper
 
     desc "setup", "Creates a new Docs Project in current directory"
     def setup
@@ -23,9 +20,10 @@ module Docs
     def build
       @examples = {:source => {}, :output => {}}
       @erb_environment = ERBEnvironment.new
+      @erb = ERBRenderer.new(@erb_environment)
       @markdown = markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, :autolink => true, :space_after_headers => true)
 
-      @erb_environment.config = @config = Config.new('config.yaml') 
+      @erb_environment.config = @config = Config.new 
       ['temp', 'output'].each do |dir|
         dir = @config.directories[dir]
         remove_file dir if File.exists? dir
@@ -37,39 +35,28 @@ module Docs
       copy_assets
     end
 
+    desc "spec", "Run example tests"
+    def spec
+      require 'rspec/core'
+      RSpec::Core::Runner.autorun
+    end
+
     private
     def load_examples 
-      examples = Dir.glob('examples/**/*')
-      examples.each do |example_name|
-        next unless File.file?(example_name)
-
-        example_file = example_name
-        if File.fnmatch?('*.erb.*', example_name)
-          create_file (example_file = "tmp/#{Digest::MD5.hexdigest(example_name)}#{File.extname(example_name)}"), render_erb_string(File.read(example_name))
-        end
-
-        @examples[:source][example_name] = File.read(example_file)
-
-        unless EXTENSIONS_TO_COMMANDS[File.extname(example_file)].nil?
-          i = IO.popen("#{EXTENSIONS_TO_COMMANDS[File.extname(example_file)]} #{example_file}")
-          @examples[:output][example_name] = i.read
-        end
-      end
-
-      @erb_environment.examples = @examples
+      @erb_environment.examples = examples('examples/**/*', @erb)
     end
 
     def build_docs
-      docs = Dir.glob('docs/**/*.mdown')
+      docs = Dir.glob("#{@config.directories['docs']}/**/*.mdown")
       docs.each do |doc|
         output_name = "output/#{doc.sub('docs/', '')[0...-5]}html"
 
-        erbed = render_erb_string(File.read(doc))
+        erbed = @erb.render(File.read(doc))
         rendered = @markdown.render(erbed)
 
         if @config.template
           @erb_environment.content = rendered 
-          rendered = render_erb_string File.read(@config.template)
+          rendered = @erb.render File.read(@config.template)
         end
 
         create_file output_name, rendered
@@ -82,11 +69,7 @@ module Docs
         FileUtils.cp(f, "output/#{f.sub('public/', '')}")
       end
     end
-
-    def render_erb_string(str)
-      ERB.new(str).result(@erb_environment.get_binding)
-    end
-   
+  
     def in_directory(directory, &block)
       previous_directory = Dir.pwd
       Dir.chdir(directory)

data/lib/docs/spec.rb

@@ -0,0 +1,19 @@
+require 'docs/example'
+require 'docs/erb_environment'
+require 'docs/config'
+
+module Docs
+  module Spec
+
+    include ExampleHelper
+    
+    def self.included(base)
+      @erb_environment = ERBEnvironment.new
+      @erb_environment.config = @config = Config.new
+      @erb = ERBRenderer.new(@erb_environment)
+
+      @examples = examples("#{@config.directories['examples']}/**/*", @erb)  
+    end
+
+  end
+end

data/lib/docs/version.rb

@@ -1,3 +1,3 @@
 module Docs
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/template/config.yaml

@@ -2,4 +2,6 @@ directories:
   temp: tmp
   output: output
   assets: public
+  docs: docs
+  examples: examples
 template: application.erb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-22 00:00:00.000000000Z
+date: 2012-02-23 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
-  requirement: &70229066023880 !ruby/object:Gem::Requirement
+  requirement: &70238574194100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.14.6
   type: :runtime
   prerelease: false
-  version_requirements: *70229066023880
+  version_requirements: *70238574194100
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &70229066023380 !ruby/object:Gem::Requirement
+  requirement: &70238574193600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 2.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *70229066023380
+  version_requirements: *70238574193600
 - !ruby/object:Gem::Dependency
   name: coderay
-  requirement: &70229066022920 !ruby/object:Gem::Requirement
+  requirement: &70238574193140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,7 +43,7 @@ dependencies:
         version: 1.0.5
   type: :runtime
   prerelease: false
-  version_requirements: *70229066022920
+  version_requirements: *70238574193140
 description: Documentation generator with support for including code examples and
   compiling them at compile time
 email:
@@ -62,7 +62,11 @@ files:
 - lib/docs.rb
 - lib/docs/config.rb
 - lib/docs/erb_environment.rb
+- lib/docs/erb_renderer.rb
+- lib/docs/example.rb
+- lib/docs/example/helper.rb
 - lib/docs/project.rb
+- lib/docs/spec.rb
 - lib/docs/version.rb
 - template/application.erb
 - template/config.yaml