rdaux 0.1.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+public/img/ditaa/

data/Gemfile

@@ -0,0 +1,9 @@
+# A sample Gemfile
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem 'rake'
+  gem 'minitest'
+end

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    rdaux (0.1.0)
+      avalanche-cli (= 0.1.0)
+      posix-spawn (= 0.3.6)
+      pygments.rb (= 0.5.1)
+      redcarpet (= 3.0.0)
+      sinatra (= 1.3.3)
+      tilt (= 1.4.1)
+      unicorn (= 4.6.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    avalanche-cli (0.1.0)
+    kgio (2.8.0)
+    minitest (5.0.6)
+    posix-spawn (0.3.6)
+    pygments.rb (0.5.1)
+      posix-spawn (~> 0.3.6)
+      yajl-ruby (~> 1.1.0)
+    rack (1.5.2)
+    rack-protection (1.5.0)
+      rack
+    raindrops (0.11.0)
+    rake (10.1.0)
+    redcarpet (3.0.0)
+    sinatra (1.3.3)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    tilt (1.4.1)
+    unicorn (4.6.2)
+      kgio (~> 2.6)
+      rack
+      raindrops (~> 0.7)
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  minitest
+  rake
+  rdaux!

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Bulat Shakirzyanov
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+# RDaux
+
+RDaux creates beautiful documentation websites from markdown files.
+It is inspired by daux.io and uses redcarpet with pygments.rb to process
+github-flavored markdown files into beautiful documentation websites and
+supports ASCII art with help of [Ditaa](http://sourceforge.net/projects/ditaa/).
+
+## Installation
+
+RDaux is a rubygem, install it by running the following in your shell:
+
+```bash
+> gem install rdaux
+```
+
+### Requirements
+
+RDaux requires Python 2.5+ for Pygments and Java 1.5+ for ditaa.
+Make sure those tools are installed and available in the `$PATH`
+
+## Usage
+
+After RDaux has been installed, you can begin using it from your cli:
+
+```bash
+> rdaux -h
+Usage: rdaux [--version] [--help] command [options] [args]
+
+Available rdaux commands are:
+  serve      Dynamically serve html documentation from a given directory
+  generate   Generates static html site using docs from given directory
+
+Common options:
+    -h, --help                       Show this message
+    -v, --version                    Show version
+```
+
+As you can see, RDaux can dynamically serve documentation from your markdown
+sources or it can generate a static documentation website. You can determine
+options available to each subcommand by running:
+
+```bash
+> rdaux <subcommand> -h|--help
+```

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/rdaux

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+root_path = File.expand_path(__FILE__ + '/../..')
+
+['lib', 'bundle'].each do |path|
+  dir = root_path + '/' + path
+
+  $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir)
+end
+
+require 'rubygems'
+
+Dir.chdir(root_path) { require 'bundler/setup' }
+
+require 'avalanche/cli'
+require 'rdaux'
+require 'rdaux/version'
+require 'rdaux/cli'
+
+extend RDaux::CLI
+
+app = Avalanche::CLI::Application.new('rdaux', RDaux::VERSION)
+
+app.command('serve [options] PATH', 'Dynamically serve html documentation from a given directory', {
+  :title       => ['--title TITLE',             'Website title (e.g. RDaux)'],
+  :description => ['--description DESCRIPTION', 'Website description, displayed under title'],
+  :author      => ['--author AUTHOR',           'Website author, defaults to $USER'],
+  :log_level   => ['--log-level LEVEL',         ['debug', 'info', 'warn', 'error', 'fatal'], 'Log level'],
+  :bind        => ['--bind ADDRESS',            'IP and port or a unix domain socket to bind on (e.g. localhost:8080 or /var/run/socket.sock)'],
+  :workers     => ['--workers NUM', Integer,    'Number of unicorn worker processes to use, defaults to 4']
+}, command(:start_serving))
+
+app.command('generate [options] PATH', 'Generates static html site using docs from given directory', {
+  :title       => ['--title TITLE',             'Website title (e.g. RDaux)'],
+  :description => ['--description DESCRIPTION', 'Website description, displayed under title'],
+  :author      => ['--author AUTHOR',           'Website author, defaults to $USER'],
+  :log_level   => ['--log-level LEVEL',         ['debug', 'info', 'warn', 'error', 'fatal'], 'Log level'],
+  :output_path => ['--output-path PATH',        'Path to store generated files in, defaults to site/ directory, next to the PATH given']
+}, command(:generate_site))
+
+app.run(ARGV)

data/lib/rdaux/cli.rb

@@ -0,0 +1,37 @@
+require 'pathname'
+require 'rdaux/container'
+
+module RDaux
+  module CLI
+    include RDaux::Container
+
+    attr_reader :options, :directory
+
+    def command(method)
+      Proc.new do |opts, args|
+        process_options(opts)
+        send(method, *args)
+      end
+    end
+
+    def process_options(options)
+      @options = options
+    end
+
+    def use_directory(directory)
+      raise 'PATH is a required argument to serve command' if directory.nil?
+
+      @directory = Pathname(directory)
+    end
+
+    def start_serving(directory = nil)
+      use_directory(directory)
+      webserver.serve(website)
+    end
+
+    def generate_site(directory = nil)
+      use_directory(directory)
+      generator.generate_static(website)
+    end
+  end
+end

data/lib/rdaux/container.rb

@@ -0,0 +1,103 @@
+require 'redcarpet'
+require 'logger'
+
+require 'rdaux/notifier'
+require 'rdaux/web/application'
+require 'rdaux/web/server'
+require 'rdaux/web/site'
+require 'rdaux/web/site/generator'
+require 'rdaux/renderer'
+require 'rdaux/logging_listener'
+
+module RDaux
+  module Container
+    def webapp
+      @webapp ||= with_config(Web::Application) do |app|
+        app.set(:markdown,  markdown)
+        app.set(:ditaa_jar, ditaa_jar)
+      end
+    end
+
+    def webserver
+      @webserver ||= with_logging(Web::Server.new(webapp, logger, public_folder, options))
+    end
+
+    def website
+      @website ||= Web::Site.new(title, description, author, directory)
+    end
+
+    def generator
+      @generator ||= with_logging(Web::Site::Generator.new(markdown, views_dir, public_folder, ditaa_jar, target_dir))
+    end
+
+    def logger
+      with_config(Logger.new($stderr)) do |l|
+        l.level     = log_level
+        l.formatter = proc { |s, d, p, m| "%s | %-10s %s\n" % [d.strftime("%T,%L"), "[#{s}]", m] }
+      end
+    end
+
+    def log_level
+      Logger.const_get(@options.fetch(:log_level, 'info').upcase)
+    end
+
+    def logging_listener
+      @logging_listener ||= LoggingListener.new(logger)
+    end
+
+    def public_folder
+      File.expand_path(__FILE__ + '/../../../public')
+    end
+
+    def ditaa_jar
+      File.expand_path(__FILE__ + '/../../../vendor/ditaa/ditaa0_9.jar')
+    end
+
+    def markdown
+      Redcarpet::Markdown.new(Renderer.new({
+        :filter_html => true,
+        :images_dir  => public_folder,
+        :ditaa_root  => '/img/ditaa'
+      }), {
+        :no_intra_emphasis   => true,
+        :tables              => true,
+        :fenced_code_blocks  => true,
+        :autolink            => true,
+        :space_after_headers => true,
+        :superscript         => true,
+        :underline           => true,
+        :highlight           => true
+      })
+    end
+
+    private
+
+    def views_dir
+      File.expand_path(__FILE__ + '/../web/views')
+    end
+
+    def title
+      options.fetch(:title, "RDaux")
+    end
+
+    def description
+      options.fetch(:description) { "Documentation for <em>#{directory.relative_path_from(Pathname(ENV['PWD']))}</em>" }
+    end
+
+    def author
+      options.fetch(:author) { ENV['USER'] }
+    end
+
+    def target_dir
+      Pathname(options.fetch(:output_path) { directory + '../site/' })
+    end
+
+    def with_logging(obj)
+      with_config(obj) {|o| o.add_listener(logging_listener)}
+    end
+
+    def with_config(obj)
+      obj.tap {|o| yield(o)}
+    end
+  end
+end

data/lib/rdaux/logging_listener.rb

@@ -0,0 +1,19 @@
+module RDaux
+  class LoggingListener
+    def initialize(logger)
+      @logger = logger
+    end
+
+    def creating_application(path)
+      @logger.debug("Creating application for: #{path}")
+    end
+
+    def adding_file(path)
+      @logger.debug("Adding file: #{path}")
+    end
+
+    def adding_directory(path)
+      @logger.debug("Adding directory: #{path}")
+    end
+  end
+end

data/lib/rdaux/notifier.rb

@@ -0,0 +1,17 @@
+module RDaux
+  module Notifier
+    def notifier_initialize
+      @__listeners__ = []
+    end
+
+    def add_listener(listener)
+      @__listeners__ << listener
+    end
+
+    def broadcast(event, *args)
+      @__listeners__.each do |listener|
+        listener.__send__(event, *args) if listener.respond_to?(event)
+      end
+    end
+  end
+end

data/lib/rdaux/renderer.rb

@@ -0,0 +1,45 @@
+require 'digest'
+require 'pygments'
+
+module RDaux
+  class Renderer < Redcarpet::Render::SmartyHTML
+    def initialize(options)
+      @images_dir = options.delete(:images_dir) { raise ":images_dir is a required option" }
+      @ditaa_root = options.delete(:ditaa_root) { raise ":ditaa_root is a required option" }
+
+      super(options)
+    end
+
+    def block_code(code, language)
+      case language
+      when nil
+        "<pre><code>#{code}</code></pre>"
+      when 'ditaa'
+        ascii2png(code)
+      else
+        highlight(code, language)
+      end
+    end
+
+    private
+
+    def highlight(code, language)
+      markup = Pygments.highlight(code, :lexer => language)
+      markup = markup.sub(/<div class="highlight"><pre>/,'<pre><code class="' + language + '">')
+      markup = markup.sub(/<\/pre><\/div>/,"</code></pre>")
+      markup
+    rescue MentosError
+      "<pre><code class=\"#{language}\">#{code}</code></pre>"
+    end
+
+    def ascii2png(code)
+      image_id = Digest::MD5.hexdigest(code)
+      png_path = @images_dir + @ditaa_root + "/#{image_id}.txt"
+      txt_path = @images_dir + @ditaa_root + "/#{image_id}.txt"
+
+      File.open(txt_path, 'w+') { |f| f.write(code) } unless File.exists?(png_path)
+
+      "<img src=\"#{@ditaa_root}/#{image_id}.png\" alt=\"Text Diagram\" class=\"img-rounded img-polaroid ditaa\">"
+    end
+  end
+end

data/lib/rdaux/version.rb

@@ -0,0 +1,3 @@
+module RDaux
+  VERSION = "0.1.0"
+end

data/lib/rdaux/web/application.rb

@@ -0,0 +1,40 @@
+require 'posix/spawn'
+require 'sinatra/base'
+
+module RDaux
+  module Web
+    class Application < Sinatra::Base
+      attr_reader :current_section
+
+      enable :logging
+
+      get '/img/ditaa/:id.png/?' do |id|
+        txt_path = settings.public_folder + "/img/ditaa/#{id}.txt"
+        png_path = settings.public_folder + "/img/ditaa/#{id}.png"
+
+        halt(404) unless File.exists?(txt_path)
+
+        Process::waitpid(POSIX::Spawn.spawn("java", '-jar', settings.ditaa_jar, txt_path, png_path))
+        File.unlink(txt_path)
+
+        send_file(png_path, :status => 201)
+      end
+
+      get '/' do
+        erb(:site)
+      end
+
+      def site
+        settings.site || halt(500)
+      end
+
+      def markdown
+        settings.markdown || halt(500)
+      end
+
+      def render_markdown(markup)
+        markdown.render(markup)
+      end
+    end
+  end
+end

data/lib/rdaux/web/server.rb

@@ -0,0 +1,44 @@
+require 'unicorn'
+require 'tmpdir'
+require 'fileutils'
+
+module RDaux
+  module Web
+    class Server
+      include Notifier
+
+      def initialize(app, logger, static_dir, options)
+        @app        = app
+        @logger     = logger
+        @static_dir = static_dir
+        @options    = options
+
+        notifier_initialize
+      end
+
+      def serve(website)
+        with_duplicate_static_dir do |dir|
+          @app.configure do
+            @app.set(:site, website)
+            @app.set(:public_folder, dir)
+          end
+
+          Unicorn::HttpServer.new(@app, {
+            :listeners        => @options.fetch(:bind, 'localhost:8080'),
+            :worker_processes => @options.fetch(:workers, 4),
+            :logger           => @logger
+          }).start.join
+        end
+      end
+
+      private
+
+      def with_duplicate_static_dir
+        Dir.mktmpdir('rdaux') do |dir|
+          FileUtils.cp_r(@static_dir + '/.', dir)
+          yield(dir)
+        end
+      end
+    end
+  end
+end

data/lib/rdaux/web/site/generator.rb

@@ -0,0 +1,66 @@
+require 'tilt'
+require 'posix/spawn'
+
+module RDaux
+  module Web
+    class Site
+      class Generator
+        include Notifier
+
+        def initialize(markdown, views_dir, static_dir, ditaa_jar, target_dir)
+          @markdown   = markdown
+          @views_dir  = views_dir
+          @static_dir = static_dir
+          @ditaa_jar  = ditaa_jar
+          @target_dir = target_dir
+
+          @cached_templates = {}
+          notifier_initialize
+        end
+
+        def generate_static(website)
+          with_duplicate_static_dir do |dir|
+            File.open("#{dir}/index.html", 'w+') do |f|
+              f.write(erb(:site, :locals => {:site => website}))
+            end
+
+            Dir.glob("#{dir}/img/ditaa/*.txt").each do |txt_path|
+              Process::waitpid(POSIX::Spawn.spawn("java", '-jar', @ditaa_jar, txt_path))
+              File.unlink(txt_path)
+            end
+
+            if File.directory?(@target_dir)
+              FileUtils.cp_r("#{dir}/.", @target_dir)
+            else
+              FileUtils.mv(dir, @target_dir)
+            end
+          end
+        end
+
+        private
+
+        def with_duplicate_static_dir
+          dir = Dir.mktmpdir('rdaux')
+
+          FileUtils.cp_r("#{@static_dir}/.", dir)
+          yield(dir)
+        ensure
+          FileUtils.remove_entry_secure(dir) if File.directory?(dir)
+        end
+
+        def erb(view, options)
+          unless @cached_templates.has_key?(view)
+            @cached_templates[view] = Tilt[:erb].new("#{@views_dir}/#{view}.erb", 1, {
+              :default_encoding => 'UTF-8'
+            })
+          end
+          @cached_templates[view].render(self, options.fetch(:locals, {}))
+        end
+
+        def render_markdown(markup)
+          @markdown.render(markup)
+        end
+      end
+    end
+  end
+end

data/lib/rdaux/web/site.rb

@@ -0,0 +1,86 @@
+module RDaux
+  module Web
+    class Site
+      attr_reader :title, :description, :author, :root
+
+      class Section
+        attr_reader   :key
+        attr_writer   :contents
+        attr_accessor :sections
+
+        def initialize(key)
+          @key = key
+        end
+
+        def title
+          @title ||= @key.split('-').map(&:capitalize).join(' ')
+        end
+
+        def contents
+          @contents && @contents.read
+        end
+
+        def has_children?
+          @sections && !@sections.empty?
+        end
+
+        def has_contents?
+          !@contents.nil?
+        end
+      end
+
+      def initialize(title, description, author, root)
+        @title       = title
+        @description = description
+        @author      = author
+        @root        = root
+      end
+
+      def sections
+        find_sections(@root)
+      end
+
+      private
+
+      def find_sections(root)
+        root.children.inject({}) do |sections, path|
+          unless path.symlink?
+            if path.file? && path.extname == '.md'
+              key = basename_to_key(base_filename(path))
+              section = get_or_create_section(key, sections)
+
+              section.contents = path
+            elsif path.directory? && !path.basename.to_s.start_with?('.')
+              key = basename_to_key(base_dirname(path))
+              section = get_or_create_section(key, sections)
+
+              section.sections = find_sections(path)
+            end
+          end
+
+          sections
+        end
+      end
+
+      def get_or_create_section(key, sections)
+        unless sections.has_key?(key)
+          sections[key] = Section.new(key)
+        end
+
+        sections[key]
+      end
+
+      def basename_to_key(basename)
+        basename.split(/[\_\- ]/).map(&:downcase).join('-')
+      end
+
+      def base_filename(path)
+        path.sub_ext('').basename.to_s.sub(/^[0-9]*[\_\-]?/, '')
+      end
+
+      def base_dirname(path)
+        path.basename.to_s.sub(/^[0-9]*[\_\-]?/, '')
+      end
+    end
+  end
+end

data/lib/rdaux/web/views/docs.erb

@@ -0,0 +1,11 @@
+<% for key, section in sections %>
+<a name="<%= base %><%= section.key %>"></a>
+<% if section.has_contents? %>
+<section class="docs-section">
+  <%= render_markdown(section.contents) %>
+</section>
+<% end %>
+<% if section.has_children? %>
+<%= erb(:docs, :locals => { :sections => section.sections, :base => section.key + '.' }) %>
+<% end %>
+<% end %>

data/lib/rdaux/web/views/nav.erb

@@ -0,0 +1,10 @@
+<% for key, section in sections %>
+  <li>
+    <a href="#<%= base %><%= section.key %>" title="<%= section.title %>"><i class="icon-chevron-right"></i><%= section.title %></a>
+    <% if section.has_children? %>
+    <ul class="nav nav-list">
+      <%= erb(:nav, :locals => { :sections => section.sections, :base => section.key + '.' }) %>
+    </ul>
+    <% end %>
+  </li>
+<% end %>