helphelp 0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2012 SUSE Linux Products GmbH
+
+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

@@ -0,0 +1,30 @@
+# Helphelp - generating online help
+
+The helphelp tool takes a directory of files formatted using Markdown [1] and
+converts it to a set of static HTML pages. It supports the usual Markdown syntax
+and the extensions provided by Maruku [2].
+
+The Mardown converted to HTML is inserted into templates provided by helphelp or
+by the caller on the command line. The support a few additional features like
+generation of a table of contents.
+
+The structure of the source directory, its subdirectories, and the files in them
+is reflected in the generated output. As a convention the tool expects file and
+directory names to start with a three digit number. This number is used to
+define the sequence of files in the structure of the online help. The numbers
+don't show up in the output.
+
+Source files are expected to have the suffix ".md".
+
+Picture files which are referenced from the markdown are scaled and copied to
+the output destination at the same location in the directory hierarchy as they
+are in the sources.
+
+There are another few non-Markdown features which are supported in the source
+files by the helphelp tool. If you insert a "#dir_toc" at the beginning of a
+line, it is replaced by a table of contents for the content of the subdirectory
+the file is located.
+
+
+[1]: http://daringfireball.net/projects/markdown/
+[2]: http://maruku.rubyforge.org/

data/Rakefile

@@ -0,0 +1,8 @@
+task :default => "test"
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end

data/bin/helphelp

@@ -0,0 +1,67 @@
+#!/usr/bin/ruby
+
+require File.expand_path('../../lib/helphelp',__FILE__)
+
+output_dir = "html"
+do_pull = false
+input_repo = nil
+
+opt = OptionParser.new
+opt.banner = "Usage: helphelp <input-repository>"
+
+opt.on( "-h", "--help", "Print this message" ) do
+  puts opt
+  exit
+end
+
+opt.on( "-o <dir>", "--output-dir <dir>", "Output directory" ) do |value|
+  output_dir = value
+end
+
+opt.on( "--pull", "Pull git before creating output" ) do
+  do_pull = true
+end
+
+opt.on( "--raw-convert <file>", "Just run the raw markdown conversion on the given file" ) do |file|
+  puts Maruku.new( File.read file ).to_html
+end
+
+begin
+  opt.parse!( ARGV )
+rescue OptionParser::InvalidOption
+  STDERR.puts $!
+  STDERR.puts opt
+  exit
+end
+
+if ARGV.size == 1
+  input_repo = ARGV[0]
+else
+  puts opt
+  exit
+end
+
+if do_pull
+  puts "Updating git repository..."
+  cmd = "cd #{File.dirname input_repo}; git pull"
+  system cmd
+end
+
+puts "Reading repository #{input_repo}"
+
+puts "Writing output..."
+if !output_dir
+  STDERR.puts "You need to specify an output directory."
+  exit 1
+end
+
+output = Output.new input_repo
+
+begin
+  output.create output_dir
+rescue ParseError => e
+  STDERR.puts "Parse error: e.message"
+  exit 1
+end
+
+puts "Done."

data/lib/helphelp.rb

@@ -0,0 +1,12 @@
+require "rubygems"
+
+require "haml"
+require "date"
+require "maruku"
+
+require "optparse"
+
+require File.expand_path('../version', __FILE__)
+require File.expand_path('../parse_error', __FILE__)
+require File.expand_path('../page', __FILE__)
+require File.expand_path('../output', __FILE__)

data/lib/output.rb

@@ -0,0 +1,205 @@
+class Output
+
+  def initialize input_repo
+    @input_repo = input_repo
+    
+    @content_width = 600
+  end
+
+  def create output_dir
+    @output_dir = output_dir
+    
+    if !File.exists? output_dir
+      Dir::mkdir output_dir
+    end
+
+    public_source_dir = File.expand_path("_view/public", @input_repo )
+    if File.exists? public_source_dir
+      public_dir = File.expand_path( "public", output_dir )
+      if !File.exists? public_dir
+        Dir::mkdir public_dir
+      end
+
+      cmd = "cp #{public_source_dir}/* #{public_dir}"
+      system cmd
+    end
+    
+    @input_path = Array.new
+    @output_path = Array.new
+
+    @root_page = Page.new
+    @root_page.directory_path = @output_path
+    @root_page.level = -1
+    
+    process_directory @input_repo, @root_page
+
+    postprocess_page @root_page
+    
+    create_pages @root_page
+  end
+
+  def postprocess_page parent_page
+    parent_page.postprocess
+    parent_page.children.each do |page|
+      postprocess_page page
+    end
+  end
+  
+  def process_directory dir, parent_page
+    Dir.entries( dir ).sort.each do |entry|
+      if entry =~ /^\d\d\d_(.*)$/
+        input_name = $1
+        full_name = input_path + "/" + entry
+        if File.directory?( full_name )
+          @input_path.push entry
+          @output_path.push input_name
+          if !File.exists? output_path
+            Dir.mkdir output_path
+          end
+
+          page = Page.new
+          parent_page.add_child page
+          page.directory_path = full_name
+          
+          process_directory full_name, page
+          @input_path.pop
+          @output_path.pop
+        else
+          file_basename = nil
+          file_format = nil
+          if input_name =~ /^(.*)\.(.*)$/
+            file_basename = $1
+            file_format = $2
+            if file_format != "md"
+              raise ParseError "Unsupported format '#{file_format}' in file " +
+                "#{input_name}."
+            end
+          else
+            raise ParseError "Input file #{input_name} doesn't have an
+extension."
+          end
+
+          page = nil
+          if file_basename == "index"
+            page = parent_page
+          else
+            page = Page.new
+            parent_page.add_child page
+          end
+
+          page.file_basename = file_basename
+          page.path = input_path + "/" + entry
+          page.content = File.read( input_path + "/" + entry )
+          page.file_format = file_format
+
+          output_file_name = file_basename + ".html"
+          if ( @output_path.empty? )
+            page.target = output_file_name
+          else
+            page.target = @output_path.join( "/" ) + "/" + output_file_name
+          end
+          page.output_file = output_path + "/" + output_file_name
+        end
+      elsif entry =~ /.*\.png$/
+        cmd = "cp #{input_path}/#{entry} #{output_path}/#{entry}"
+        system cmd
+        cmd = "mogrify -resize #{@content_width}x5000 #{output_path}/#{entry}"
+        STDERR.puts "MOGRIFY: #{cmd}"
+        system cmd
+      end
+    end
+  end
+
+    def create_pages parent_page
+    parent_page.children.each do |page|
+      if page.content
+        create_page page
+      end
+      create_pages page
+    end
+  end
+
+  def input_path
+    @input_repo + "/" + @input_path.join( "/" )
+  end
+  
+  def output_path
+    @output_dir + "/" + @output_path.join( "/" )
+  end
+  
+  def create_page page
+    puts "CREATE PAGE #{page.path} #{page.output_file}"
+    @page = page
+    create_file "_view/template.haml", page.output_file
+  end
+  
+  def create_file template_name, output_filename
+    template = File.read File.expand_path(template_name, @input_repo )
+    engine = Haml::Engine.new template
+    
+    File.open output_filename, "w" do |file|
+      file.puts engine.render( binding )
+    end
+  end
+
+  def css name
+    "<link rel='stylesheet' href='#{@page.relative_site_root}public/#{name}.css'" + 
+    " type='text/css'>"
+  end
+
+  def title
+    @page.title
+  end
+  
+  def render_content
+    @out = ""
+
+    doc = Maruku.new @page.content
+    o doc.to_html
+
+    @out
+  end
+
+  def render_toc
+    @out = ""
+
+    on "<h1>Table of contents</h1>"
+    render_toc_section @root_page
+
+    @out
+  end
+  
+  def render_toc_section parent_page
+    on "<ul>"
+    parent_page.children.each do |page|
+      o "<li>"
+      title = page.title
+      if page.has_children?
+        title += " >"
+      end
+      if page == @page
+        o "<span class=\"current-page\">#{title}</span>"
+      else
+        if page.title && !page.title.empty?
+          o "<a href='#{@page.relative_site_root}#{page.target}'>#{title}</a>"
+        end
+      end
+      on "</li>"
+      if @page == page || ( page.has_children? && @page.has_parent( page ) )
+        render_toc_section page
+      end
+    end
+    on "</ul>"
+  end
+    
+  protected
+  
+  def o txt
+    @out += txt.to_s
+  end
+
+  def on txt
+    o txt + "\n"
+  end
+  
+end

data/lib/page.rb

@@ -0,0 +1,88 @@
+class Page
+
+  attr_accessor :children, :directory_path, :path, :target, :level,
+    :file_format, :output_file, :parent, :file_basename
+  attr_reader :content, :title
+  
+  def initialize
+    @level = 0
+    @children = Array.new
+  end
+
+  def add_child child
+    @children.push child
+    child.parent = self
+    child.level = self.level + 1
+  end
+  
+  def has_children?
+    !@children.empty?
+  end
+
+  def has_parent p
+    if self.parent == p
+      return true
+    else
+      if self.parent.nil?
+        return false
+      else
+        return self.parent.has_parent p
+      end
+    end
+  end
+  
+  def content= content
+    @content = preprocess content
+  end
+
+  def postprocess
+    return unless @content
+
+    out = ""
+    @content.each_line do |line|
+      if line =~ /^#dir_toc/
+        if self.has_children?
+          out += "<ul>"
+          self.children.each do |child|
+            out += "<li>"
+            out += "<a href='#{self.relative_site_root}#{child.target}'>#{child.title}</a>"
+            out += "</li>"
+          end
+          out += "</ul>"
+        end
+      else
+        out += line
+      end
+    end
+    @content = out
+  end
+
+  def relative_site_root
+    out = ""
+
+    effective_level = self.level
+    if self.file_basename == "index"
+      effective_level += 1
+    end
+    
+    effective_level.times do
+      out += "../"
+    end
+    
+    out
+  end
+
+  protected
+  
+  def preprocess content
+    out = ""
+    content.each_line do |line|
+      out += line
+      if !@title && line =~ /^# (.*)$/
+        @title = $1
+      end
+    end
+    out
+  end
+  
+end

data/lib/parse_error.rb

@@ -0,0 +1,2 @@
+class ParseError < StandardError
+end

data/lib/version.rb

@@ -0,0 +1,5 @@
+module Helphelp
+
+  VERSION = "0.0.1"
+
+end

data/test/page_test.rb

@@ -0,0 +1,56 @@
+require File.expand_path('../test_helper', __FILE__)
+
+class PageTest < Test::Unit::TestCase
+
+  def test_title
+    p = Page.new
+    p.content = "# Hallo"
+    
+    assert_equal "Hallo", p.title
+  end
+
+  def test_preprocess
+    content = ""
+    content += "# My Title\n"
+    content += "\n"
+    content += "Some text"
+    content += "\n"
+    content += "## Sub Title\n"
+    content += "\n"
+    content += "# Sneaky wrong title"
+    
+    p = Page.new
+    p.content = content
+    
+    assert_equal content, p.content
+    assert_equal "My Title", p.title
+  end
+  
+  def test_has_parent
+    parent = Page.new
+    child1 = Page.new
+    parent.add_child child1
+    child2 = Page.new
+    parent.add_child child2
+    grandchild11 = Page.new
+    child1.add_child grandchild11
+    grandchild12 = Page.new
+    child1.add_child grandchild12
+    grandchild21 = Page.new
+    child2.add_child grandchild21
+    
+    assert_equal true, child1.has_parent( parent )
+    assert_equal true, child2.has_parent( parent )
+    assert_equal true, grandchild11.has_parent( child1 )
+    assert_equal false, grandchild11.has_parent( child2 )
+    assert_equal true, grandchild11.has_parent( parent )
+    assert_equal true, grandchild12.has_parent( child1 )
+    assert_equal true, grandchild12.has_parent( parent )
+    assert_equal false, grandchild12.has_parent( child2 )
+    assert_equal true, grandchild12.has_parent( child1 )
+    assert_equal true, grandchild21.has_parent( child2 )
+    assert_equal false, grandchild21.has_parent( child1 )
+    assert_equal true, grandchild21.has_parent( parent )    
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require File.expand_path('../../lib/helphelp',__FILE__)
+
+require 'test/unit'

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: helphelp
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Cornelius Schumacher
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-02 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: |
+  Generator for turning a directory hierarchy of markdown files into a static
+  set of HTML pages. It's targeted at providing online help for web application.
+
+email: cschum@suse.de
+executables: 
+- helphelp
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- Rakefile
+- LICENSE
+- lib/parse_error.rb
+- lib/version.rb
+- lib/helphelp.rb
+- lib/page.rb
+- lib/output.rb
+- bin/helphelp
+- test/page_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/susestudio/helphelp
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: Online help generator
+test_files: []
+