murdoc 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ef249b35659b0df1ac35d233d7ded20dc29e45b
-  data.tar.gz: 7017b589cae5baf9511e1aaf065931b32d30c75a
+  metadata.gz: 7770978eea693f9a8464f272ed228ecd76fc3493
+  data.tar.gz: 9943ca4db60ec141f2088ff9d652f5f2949fbd7c
 SHA512:
-  metadata.gz: 935006a39b60ce7b2d6c2d1c4eb8247758f36a60a2ce2174757d8befea55231dc5916b3c167d8d1c26b1f693c7eff06b0a7c7c4ca0f2713c12791b0b9d102e15
-  data.tar.gz: 87622f60399b0217f751cfa09b60eeea353d2af8a00727293057feaffac8de8ebc25ad3a7a5f5a16c186e57466214cb725911abde2fddaf922697ae7682a6227
+  metadata.gz: 858b23df3485164ec8630973857152ee8f90901bf6a1ae903cbadb3ac64548e239fb3d8b8eb6d1a06891d14541a108829c09f853f04932c19178f7f069ee208e
+  data.tar.gz: cdc220eb7da112690d7605b0ee4c54db009112dfad38ebf4b7674b627128bd92222085a7121b7b846198eb70d378f5809536e5d665eae5140628f91fbff74aa9

data/README.md

@@ -1,12 +1,29 @@
-Murdoc -- ruby documenter
+Murdoc — a ruby documenter
 ==============================
 
 Murdoc is a doccu-style annotated documentation generator.
 
-You may also want to see:
+Rationale
+---------
+
+Sometimes it makes sense to create a guide, a story told by code and comments side by side. Murdoc generates a pretty html for such a story.
+
+Example
+-------
+
+Demo at [GH.pages](http://jsus.github.io/murdoc).
+
+See also:
+
+* [example](http://jsus.github.io/murdoc/docs) of integration with [jsus](http://github.com/jsus/jsus)
+
+Usage
+-----
+
+* `gem install murdoc`
+* `murdoc <input file> <output html file>` **or**
+* `murdoc <input file 1> <input file 2> ... <output html file>`
 
-* [docco.coffee](http://jashkenas.github.com/docco/)
-* [Rocco](http://rtomayko.github.com/rocco/)
 
 Dependencies
 ------------
@@ -14,16 +31,14 @@ Dependencies
 * Haml
 * Either RDiscount (for MRI rubies) or Kramdown (for non-mri rubies)
 
-Example
--------
-
-See example at [GH.pages](http://jsus.github.com/murdoc).
-
-See also:
-* [example](http://jsus.github.com/murdoc/docs) of integration with [jsus](http://github.com/jsus/jsus)
-* [LSD documentation guides](https://github.com/lovelyscalabledrawings/lsd-guides/tree/gh-pages/grid)
 
 License
 -------
 
 Public domain, see UNLICENSE file.
+
+See also
+--------
+
+* [docco.coffee](http://jashkenas.github.io/docco/)
+* [Rocco](http://rtomayko.github.io/rocco/)

data/bin/murdoc-tree

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+require "optparse"
+$: << File.expand_path("../../lib/", __FILE__)
+require "murdoc"
+
+options = {}
+
+option_parser = OptionParser.new do |opts|
+  opts.banner = "#{$0} <input dir> <output dir>"
+
+  opts.on('--index-template [FILENAME]', 'template to use for index files') do |template|
+    options[:index_template] = template
+  end
+
+  opts.on('--index-stylesheet [FILENAME]', 'stylesheet to use for index files') do |stylesheet|
+    options[:index_stylesheet] = stylesheet
+  end
+
+  opts.on('--template [FILENAME]', 'template to use for other files') do |template|
+    options[:template] = template
+  end
+
+  opts.on('--stylesheet [FILENAME]', 'stylesheet to use for other files') do |stylesheet|
+    options[:stylesheet] = stylesheet
+  end
+
+  opts.on("--[no-]syntax-highlight", "Highlight syntax using pygments") do |h|
+    options[:highlight] = h
+  end
+
+  opts.on("--do-not-count-comment-lines") do |dncl|
+    options[:do_not_count_comment_lines] = dncl
+  end
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+end
+
+option_parser.parse!
+
+if ARGV.size != 2
+  puts option_parser
+  exit(1)
+else
+  Murdoc.generate_tree(ARGV[0], ARGV[1], false, nil, options)
+end

data/lib/murdoc.rb

@@ -8,20 +8,29 @@
 # [ro]: "http://rtomayko.github.com/rocco"
 #
 
+require 'fileutils'
+require 'pathname'
 
 module Murdoc
-  AnnotatedFile = Struct.new(:filename, :source, :source_type, :paragraphs, :formatted_paragraphs)
+  # `AnnotatedFile` is a struct we pass into our templates
+  AnnotatedFile = Struct.new(:filename, :metadata, :source, :source_type, :paragraphs, :formatted_paragraphs)
 
+  # `Murdoc.annotate` arguments are gathered from CLI utility
+  #
+  # `highlight` regulates syntax highlighting and `do_not_count_comment_lines` flag
+  # toggles counting comment lines towards line numbering in the output.
   def self.annotate(filename, highlight = true, do_not_count_comment_lines = false)
     filename = File.expand_path(filename)
     annotator = Annotator.from_file(filename, nil, do_not_count_comment_lines)
     AnnotatedFile.new(filename,
+        annotator.metadata,
         annotator.source,
         annotator.source_type,
         annotator.paragraphs,
         annotator.paragraphs.map {|p| FormattedParagraph.new(p, highlight) })
   end
 
+  # Generate a single file story
   def self.generate_from_file(input, output, options = {})
     options = default_options.merge(options)
     annotator = Annotator.from_file(input, nil)
@@ -32,6 +41,7 @@ module Murdoc
     end
   end
 
+  # ... or use multiple files
   def self.generate_from_multiple_files(input_files, output, options = {})
     options = default_options_for_multiple_files.merge(options)
     annotated_files = input_files.map {|fn| annotate(fn, options[:highlight], options[:do_not_count_comment_lines]) }
@@ -41,6 +51,69 @@ module Murdoc
     end
   end
 
+  # Generate a documentation tree
+  def self.generate_tree(input_dir, output_dir, has_parent = false, base_dir = nil, options = {})
+    options = default_options_for_tree.merge(options)
+    input_dir = Pathname(input_dir).expand_path
+    output_dir = Pathname(output_dir).expand_path
+    base_dir ||= input_dir
+
+    FileUtils.mkdir_p(output_dir)
+
+    entries = input_dir.children
+
+    directories = entries.select(&:directory?).
+                          reject {|dir| dir == output_dir }.
+                          reject {|dir| dir.basename.to_s.start_with?('.')}
+    directories.each do |dir|
+      next if dir == output_dir
+      generate_tree(dir,
+                    output_dir + dir.relative_path_from(input_dir),
+                    true,
+                    base_dir,
+                    options)
+    end
+
+    files = entries.select(&:file?).select {|file| Languages.detect(file.to_s) }
+    files.each do |file|
+      relpath = file.relative_path_from(input_dir)
+      generate_from_file(file, "#{output_dir}/#{relpath}.html", {
+        highlight: options[:highlight],
+        template: options[:template],
+        stylesheet: options[:stylesheet],
+        do_not_count_comment_lines: options[:do_not_count_comment_lines]
+      })
+    end
+
+    unless files.empty? && directories.empty?
+      generate_index("#{output_dir}/index.html", {
+       current_directory: input_dir,
+       files: files,
+       directories: directories,
+       has_parent: has_parent,
+       base_dir: base_dir,
+       template: options[:index_template],
+       stylesheet: options[:index_stylesheet]
+      })
+    end
+  end
+
+  def self.generate_index(fn, options)
+    options = default_options_for_index.merge(options)
+    File.open(fn, 'w+') do |f|
+      f.puts Renderer.new(options[:template]).render({
+        stylesheet: File.read(options[:stylesheet]),
+        base_dir: options[:base_dir],
+        has_parent: options[:has_parent],
+        current_directory: options[:current_directory],
+        files: options[:files],
+        directories: options[:directories]
+      })
+    end
+  end
+
+
+  # Rest is self-explanatory
   def self.default_options
     @options ||= {
       template:   "#{markup_dir}/template.haml",
@@ -50,16 +123,41 @@ module Murdoc
   end
 
   def self.default_options_for_multiple_files
-    @options ||= {
+    @options_multi ||= {
       template:   "#{markup_dir}/template_multifile.haml",
       stylesheet: "#{markup_dir}/stylesheet.css",
       highlight: true
     }
   end
 
+  def self.default_options_for_tree
+    @options_tree ||= {
+      index_template: default_options_for_index[:template],
+      index_stylesheet: default_options_for_index[:stylesheet],
+      template: default_options[:template],
+      stylesheet: default_options[:stylesheet],
+      highlight: default_options[:highlight],
+      do_not_count_comment_lines: false
+    }
+  end
+
+  def self.default_options_for_index
+    @options_index ||= {
+      template: "#{markup_dir}/template_index.haml",
+      stylesheet: "#{markup_dir}/stylesheet.css"
+    }
+  end
+
   def self.markup_dir
     File.expand_path("../..", __FILE__)+ "/markup"
   end
+
+
+  def self.try_load_yaml(yaml)
+    YAML.load(yaml)
+  rescue => e
+    nil
+  end
 end
 
 require "murdoc/annotator"

data/lib/murdoc/annotator.rb

@@ -1,7 +1,9 @@
+require 'yaml'
+
 module Murdoc
   class Annotator
     attr_accessor :source
-
+    attr_accessor :metadata
     # Attribute accessor containing the resulting paragraphs
     attr_accessor :paragraphs
 
@@ -11,14 +13,15 @@ module Murdoc
     # `source` string contains annotated source code
     # `source_type` is one of supported source types (currently `[:ruby, :javascript]`)
     def initialize(source, source_type, do_not_count_comment_lines = false)
+      self.source = source
       self.source_type = source_type
-      self.language    = Languages.get(source_type)
-      self.source      = source
-      self.paragraphs  = if !language.annotation_only?
-        Scanner.new(language).call(source, do_not_count_comment_lines)
+      self.language = Languages.get(source_type)
+      self.paragraphs = if !language.annotation_only?
+        Scanner.new(language).call(self.source, do_not_count_comment_lines)
       else
-        [Paragraph.new('', source, 0, nil)]
+        [Paragraph.new('', self.source, 0, nil)]
       end
+      extract_metadata!
     end
 
 
@@ -30,6 +33,15 @@ module Murdoc
                do_not_count_comment_lines)
     end
 
+    def extract_metadata!
+      if paragraphs.count > 0 && paragraphs[0].annotation =~ /\A\s*---\n(.*?)\n\s*---\n?(.*)\z/m
+        paragraphs[0].annotation = $2
+        self.metadata = Murdoc.try_load_yaml($1)
+      else
+        self.metadata = {}
+      end
+    end
+
     def source_type
       @source_type
     end

data/lib/murdoc/formatted_paragraph.rb

@@ -3,7 +3,7 @@ module Murdoc
   class FormattedParagraph
     extend Forwardable
 
-    def_delegators :paragraph, :annotation, :source, :starting_line, :source_type
+    def_delegators :paragraph, :annotation, :source, :starting_line, :source_type, :metadata
 
     attr_reader :paragraph
     attr_reader :highlight

data/lib/murdoc/paragraph.rb

@@ -6,6 +6,7 @@ rescue LoadError
 end
 require "cgi"
 require "tempfile"
+require "yaml"
 
 module Murdoc
   class Paragraph
@@ -13,12 +14,23 @@ module Murdoc
     attr_accessor :annotation
     attr_accessor :source_type
     attr_accessor :starting_line
+    attr_accessor :metadata
 
     def initialize(source, annotation, starting_line = 0, source_type = nil)
       self.source = source
       self.annotation = annotation
       self.starting_line = starting_line
       self.source_type = source_type
+      extract_metadata!
+    end
+
+    def extract_metadata!
+      if annotation =~ /(.*\n)?^---!([^\n]*)\n?(.*)\z/m
+        self.metadata = Murdoc.try_load_yaml($2)
+        self.annotation = $1.to_s + $3.to_s
+      else
+        self.metadata = {}
+      end
     end
   end
 end

data/lib/murdoc/version.rb

@@ -1,3 +1,3 @@
 module Murdoc
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/markup/template.haml

@@ -2,10 +2,16 @@
 %html
   %head
     %title Murdoc
-    %style=stylesheet
+    %style= stylesheet
   %body
     .document{:class => annotated_file.source_type}
+      /
+        metadata:
+        = annotated_file.metadata.inspect
       - annotated_file.formatted_paragraphs.each do |p|
+        /
+          paragraph metadata:
+          = p.metadata.inspect
         - unless p.annotation.empty?
           %section= p.formatted_annotation
         - unless p.source.empty?

data/markup/template_index.haml

@@ -0,0 +1,20 @@
+!!!
+- reldir = current_directory == base_dir ? base_dir.basename : current_directory.relative_path_from(base_dir)
+%html
+  %head
+    %title Murdoc /  #{reldir}
+    %style= stylesheet
+  %body
+    .document.index
+      %section
+        %h2 #{reldir}
+        %ul
+          - if has_parent
+            %li
+              %a{:href => "../index.html"} ..
+          - directories.each do |dir|
+            %li
+              %a{:href => "#{dir.basename}/index.html"}= dir.basename
+          - files.each do |file|
+            %li
+              %a{:href => "#{file.basename}.html"}= file.basename

data/markup/template_multifile.haml

@@ -6,7 +6,13 @@
   %body
     - annotated_files.each do |af|
       .document{:class => af.source_type}
+        /
+          metadata:
+          = af.metadata.inspect
         - af.formatted_paragraphs.each_with_index do |p, j|
+          /
+            paragraph metadata:
+            = p.metadata.inspect
           %section
             - if j == 0
               %label= File.basename(af.filename)

data/spec/murdoc/annotator_spec.rb

@@ -124,4 +124,23 @@ describe Murdoc::Annotator do
       subject.paragraphs[0].source.should == "def hi\n\nend"
     end
   end
+
+  describe "metadata extraction" do
+    subject { described_class.new("# ---\n# foo: 'bar'\n# baz: 'foobar'\n# ---\nhello, world!", :ruby) }
+    it "extracts and parses yaml blocks in the beginning of the file" do
+      subject.metadata.should == {
+        'foo' => 'bar',
+        'baz' => 'foobar'
+      }
+    end
+
+    it "cuts metadata from the paragraph annotation text" do
+      subject.paragraphs[0].annotation.should_not include('---')
+    end
+
+    it "doesn't raise on invalid yaml" do
+      subject = described_class.new("---\n{\n---\nfoo bar", :ruby)
+      subject.metadata.should == {}
+    end
+  end
 end

data/spec/murdoc/paragraph_spec.rb

@@ -17,5 +17,17 @@ describe Murdoc::Paragraph do
     it "should optionally set starting line" do
       described_class.new("", "", 666, :ruby).starting_line.should == 666
     end
+
+    it "extracts metadata" do
+      subject = described_class.new("", "---! {'foo': 'bar'}\nbaz")
+      subject.metadata.should == {'foo' => 'bar'}
+      subject.annotation.should == 'baz'
+    end
+
+    it "extracts metadata from the middle of annotation too" do
+      subject = described_class.new("", "foo\n---! {bar: 'baz'}\nfoo2")
+      subject.metadata.should == {'bar' => 'baz'}
+      subject.annotation.should == "foo\nfoo2"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: murdoc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Mark Abramov
@@ -99,6 +99,7 @@ email: markizko@gmail.com
 executables:
 - murdoc
 - murdoc-strip-comments
+- murdoc-tree
 extensions: []
 extra_rdoc_files: []
 files:
@@ -112,6 +113,7 @@ files:
 - UNLICENSE
 - bin/murdoc
 - bin/murdoc-strip-comments
+- bin/murdoc-tree
 - lib/murdoc.rb
 - lib/murdoc/annotator.rb
 - lib/murdoc/formatted_paragraph.rb
@@ -127,6 +129,7 @@ files:
 - lib/murdoc/version.rb
 - markup/stylesheet.css
 - markup/template.haml
+- markup/template_index.haml
 - markup/template_multifile.haml
 - murdoc.gemspec
 - spec/murdoc/annotator_spec.rb