richmond 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fe3d2cb81c934c3cfb710affd81ab50331357ff2
+  data.tar.gz: fcdccef945b2ad8d8db0961a668b4f520abf0d8f
+SHA512:
+  metadata.gz: 4b12e08234efb1b9c2028e20ca0271509735fbb0c59ba0be91415487838c819734e87ae543f0152e494a499b7efe718e579f1efa1ebe2994ad9410acaf093775
+  data.tar.gz: 1b972cf6666d3f8cd9c389c08d4eb83de34cca9382be74f4e1d2580bef05a7a87ed2fe18dd74f800998446d02ac6c705b04d12fd544e8321662fb23a4a15a986

data/.autotest

@@ -0,0 +1,20 @@
+require "autotest/bundler"
+require "autotest/restart"
+
+Autotest.add_hook :initialize do |autotest|
+  %w{.git ._* vendor tmp log doc output}.each do |exception|
+    autotest.add_exception(exception)
+  end
+end
+
+CLEAR = "\e[2J\e[f"
+LINE  = "\n"*2 + '-'*80 + "\n"*2
+
+##
+#  # From autotest/growl
+#    # Set the label and clear the terminal.
+Autotest.add_hook :run_command do
+  print LINE
+  print CLEAR 
+  false
+end

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+/output

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in richmond.gemspec
+gemspec

data/README.md

@@ -0,0 +1,66 @@
+# Richmond
+
+Richmond is a solution for culling documentation from files in a repo.
+
+## What's it for?
+
+I was not happy with existing solutions for generating swagger documentation
+from ruby code. For this reason I started hand-editing the swagger JSON files.
+This became tedious over time, and I decided that editing the files in YAML
+would be nicer. This solution worked well, but still required a lot of context-
+switching between the YAML files and the api implementation. I wrote richmond
+so that I could do this:
+
+    =begin output-file: swagger.yaml
+      api: /my/url/{param1}
+        parameters
+        - name: param1
+      ... snipped for brevity
+    =end
+    get '/my/url/:param1' do
+      param1 = params[:param1]
+      ... snipped for brevity
+    end
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'richmond'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install richmond
+
+## Usage
+
+    Richmond.generate dir
+
+This command will cause Richmond to scan all files in dir, recursively.
+The tool looks for ruby comment blocks in the following format:
+
+    =begin output-file: <output file name>
+      some text
+    =end
+
+Successive blocks targeting the same output file can be written as follows:
+
+    =begin append
+      some more text
+    =end
+
+Richmond will take any text in the block and insert it into the specified output file.
+
+## Contributing
+
+1. Fork it ( https://github.com/crmckenzie/richmond/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+require 'pry'
+Dir.glob('tasks/**/*.rake').each(&method(:import))
+
+task :default => :spec 

data/bin/richmond

@@ -0,0 +1,6 @@
+require_relative '../lib/richmond.rb'
+dir = ARGV[0]
+
+puts "scanning directory #{dir} for files"
+Richmond.generate dir
+

data/lib/richmond/logging.rb

@@ -0,0 +1,31 @@
+require 'logger'
+
+module Richmond
+  module Logging
+
+    class << self
+     
+      def logger
+        @logger ||= Logger.new $stdout 
+      end
+
+      def logger=(value)
+        @logger = value
+      end
+
+    end
+
+    # Addition
+    def self.included(base)
+      class << base
+        def logger
+          Logging.logger
+        end
+      end
+    end
+
+    def logger
+      Logging.logger
+    end
+  end
+end

data/lib/richmond/rtfm.rb

@@ -0,0 +1,125 @@
+require 'find'
+require 'ostruct'
+
+module Richmond
+
+  class RTFM
+
+    attr_accessor :record_pattern, :end_record_pattern, :output_file_pattern
+
+    include Richmond::Logging
+
+    def initialize 
+      @record_pattern      =/^\=begin.*(output-file:\s+.*|append)/i 
+      @output_file_pattern = /output-file:\s+.*\s*/i
+      @end_record_pattern  = /^\=end/i
+      @mode                = :paused
+    end 
+
+    def parse_output_file(line)
+      match = line.match output_file_pattern
+      smatch = match
+        .to_s
+        .gsub(/output-file:/, '')
+        .strip
+
+      File.expand_path smatch
+    end
+
+    def scan(dir)
+      logger.info "beginning scan"
+      result = scan_files Richmond.find_files_in_dir dir
+      logger.info "scan finished"
+      result
+    end
+
+    def scan_files(files)
+      @result = ScanResult.new
+
+      files.each do |file|
+        dir = File.dirname file
+        @input_filename = File.expand_path file
+        @output_filename = default_output_filename dir
+        
+        lines = File.readlines file
+        lines.each_with_index do |line, i|
+          line.encode!('UTF-8', 'UTF-8', :invalid => :replace)
+          #begin
+            end_recording! line if end_recording? line
+            record! line if recording?
+            begin_recording! line if begin_recording? line
+          #rescue Exception => error 
+           # logger.debug "error recording line: #{file}: line: #{i}: #{line} => #{error}"
+          #end
+          end
+      end
+
+      @result
+    end
+
+    def emit(input)
+      logger.info "begin emitting files"
+      input.each_pair do |filename, lines|
+        assert_directory_exists filename
+        logger.info "writing #{filename}"
+        File.open(filename, 'w') do |file|
+          lines.each {|line| file.write line }
+        end
+      end
+      logger.info "finished emitting files"
+      input.keys
+    end
+    
+    def begin_recording?(line)
+      return false if line.nil?
+      return true if line.match record_pattern
+      false
+    end
+    
+    def end_recording?(line)
+      line.match end_record_pattern
+    end
+
+    private
+
+    def begin_recording!(line)
+      @mode = :recording 
+      
+      if set_output_file? line
+        @output_filename = parse_output_file line
+      end
+      logger.debug "---#{line}"
+      logger.info "---begin recording into #{@output_filename} from #{@input_filename}"
+    end
+
+    def end_recording!(line)
+      @mode = :paused 
+      logger.info "---end recording"
+    end
+
+    def recording?
+      @mode == :recording
+    end
+
+    def record! line
+      @result.output[@output_filename].push line 
+      @result.input[@input_filename].push line 
+    end
+
+    def set_output_file?(line)
+      line.match output_file_pattern
+    end
+
+    def assert_directory_exists(filename)
+      dirname = File.dirname(filename)
+      unless File.directory?(dirname)
+        FileUtils.mkdir_p(dirname)
+      end
+    end
+
+    def default_output_filename(dir)
+      File.join(dir,'output', 'richmond.output')
+    end
+
+  end
+end

data/lib/richmond/scan_result.rb

@@ -0,0 +1,16 @@
+class ScanResult
+  attr_accessor :input, :output
+
+  def initialize
+    @input  = key_array_hash 
+    @output = key_array_hash 
+  end
+
+  private
+  def key_array_hash
+    Hash.new {|hash, key| hash[key] = [] }
+  end
+
+end
+
+

data/lib/richmond/version.rb

@@ -0,0 +1,3 @@
+module Richmond
+  VERSION = "0.2.0"
+end

data/lib/richmond.rb

@@ -0,0 +1,30 @@
+require "richmond/version"
+require 'richmond/logging'
+require 'richmond/scan_result'
+require 'richmond/rtfm'
+require 'find'
+
+module Richmond
+
+  @@find_files_in_dir = lambda do |dir|
+    files = Find.find(dir).to_a
+    files.reject! {|f| File.directory? f}
+    files.reject! {|f| f.split('/').include? '.git' }
+    files
+  end
+
+  def self.filter(&block)
+    @@find_files_in_dir = block
+  end
+
+  def self.find_files_in_dir(dir)
+    @@find_files_in_dir.call dir
+  end
+
+  def self.generate(dir)
+    rtfm = RTFM.new
+    scan = rtfm.scan dir
+    rtfm.emit scan.output
+  end
+
+end

data/richmond.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'richmond/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "richmond"
+  spec.version       = Richmond::VERSION
+  spec.authors       = ["crmckenzie"]
+  spec.email         = ["crmckenzie@gmail.com"]
+  spec.summary       = %q{scrap files for content and emit an aggregate file}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency 'autotest'
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec-autotest"
+  spec.add_development_dependency "pry"
+
+end

data/spec/lib/rtfm_spec.rb

@@ -0,0 +1,160 @@
+require_relative '../spec_helper'
+
+describe Richmond::RTFM do
+
+  let!(:dir) {
+    file = File.expand_path('../../', __FILE__)
+    dir = File.dirname(file)
+    dir
+  }
+
+  subject {
+    Richmond::RTFM.new 
+  }
+  
+  describe '.parse_output_file' do
+    it 'pulls the output-file out of the start line' do
+      line = '=begin richmond output-file: output/testfile.output'
+      expect(subject.parse_output_file line).to eq File.expand_path('output/testfile.output')
+    end
+  end
+
+  describe '.begin_recording?' do
+
+    it "standard form" do
+      line = '=begin output-file: output/testfile.output'
+      expect(subject.begin_recording? line).to eq true 
+    end
+    
+    it 'append' do
+      expect(subject.begin_recording? '=begin append').to eq true
+    end
+
+    it 'rejects nil' do
+      expect(subject.begin_recording? nil).to eq false
+    end
+
+    it 'rejects gobbledygook' do
+      expect(subject.begin_recording? 'gobbledygook').to eq false
+    end
+
+    it 'rejects standard comment block' do
+      expect(subject.begin_recording? '=begin').to eq false
+    end
+
+  end
+
+  describe '.rtfm' do
+    let!(:result) { subject.scan dir }
+
+    describe 'simple comment block' do
+
+=begin output-file: output/richmond.output 
+this:
+  is: some
+  yaml:
+  - array item 1
+  - array item 2
+=end
+
+      it 'is not nil' do
+        expect(result).to_not eq nil
+      end
+
+      describe 'input' do
+        it 'contains a key for the file' do
+          filename = File.expand_path __FILE__
+          expect(result.input).to have_key(filename)
+        end
+
+        it 'documents which comments came from which file' do
+          lines = result.input[File.expand_path __FILE__]
+          expect(lines.size).to eq 9 
+        end
+      end
+
+      describe 'output' do
+        it 'has output filename' do
+
+          default_filename = File.join(File.dirname(File.expand_path('../../', __FILE__)), 'output', 'richmond.output')
+          expect(result.output).to have_key(default_filename), result.output.keys 
+
+          lines = result.output[default_filename]
+          expect(lines.first).to eq "this:\n"
+          expect(lines.last).to eq "  - array item 2\n" 
+        end
+      end
+
+    end
+
+    describe 'comment blocks with identified output files' do
+=begin output-file: output/file1.txt
+  file 1 comments
+=end
+
+=begin output-file: output/file2.txt
+  file 2 comments
+=end
+
+=begin output-file: output/file1.txt
+  some more file 1 comments
+=end
+
+=begin append 
+  this line should appear in the output/file1.txt
+=end
+
+      it "should have keys for file1.txt and file2.txt" do
+        expect(result.output).to have_key(File.expand_path 'output/file1.txt')
+        expect(result.output).to have_key(File.expand_path 'output/file2.txt')
+      end
+
+      it 'should have 1 line for file 2' do
+        expect(result.output[File.expand_path 'output/file2.txt']).to include "  file 2 comments\n"
+      end
+
+      it 'should merge file 1 lines from all relevant comment blocks' do
+        expect(result.output[File.expand_path 'output/file1.txt']).to include("  file 1 comments\n")
+        expect(result.output[File.expand_path 'output/file1.txt']).to include("  some more file 1 comments\n")
+        expect(result.output[File.expand_path 'output/file1.txt']).to include("  this line should appear in the output/file1.txt\n")
+      end
+
+    end
+
+    describe 'comment block without richmond identifier' do
+=begin some random comment block
+  some random comments
+  should not change the test results for the richmond comment blocks
+=end
+    end
+  end
+
+  describe '.emit' do
+    let!(:input_result) { subject.scan dir }
+
+    before(:each) do
+      input_result.output.each_pair do |file, lines|
+        if File.exists? file
+          File.delete file
+        end
+      end
+    end
+
+    let!(:emit_result) { subject.emit input_result.output }
+
+    describe 'files created' do
+      it 'emit_result is not nil' do
+        expect(emit_result).to_not be nil
+      end
+
+      it 'creates the output files' do
+        input_result.output.keys.each {|file|
+          expect(File.exists? file).to eq(true), file
+        }
+      end
+
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require_relative '../lib/richmond.rb'
+require 'pry'

data/tasks/rspec.rake

@@ -0,0 +1,6 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  pattern = Dir['spec/**/*_spec.rb']
+  t.pattern = pattern 
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: richmond
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- crmckenzie
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: autotest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-autotest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- crmckenzie@gmail.com
+executables:
+- richmond
+extensions: []
+extra_rdoc_files: []
+files:
+- ".autotest"
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- README.md
+- Rakefile
+- bin/richmond
+- lib/richmond.rb
+- lib/richmond/logging.rb
+- lib/richmond/rtfm.rb
+- lib/richmond/scan_result.rb
+- lib/richmond/version.rb
+- richmond.gemspec
+- spec/lib/rtfm_spec.rb
+- spec/spec_helper.rb
+- tasks/rspec.rake
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: scrap files for content and emit an aggregate file
+test_files:
+- spec/lib/rtfm_spec.rb
+- spec/spec_helper.rb