rundoc 1.0.0 → 1.0.1

data/bin/rundoc

@@ -15,12 +15,11 @@ $: << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
 require 'rundoc'
 require 'thor'
 
-class RundocCLI < Thor
+class RundocThorCLI < Thor
 
   def initialize(*args)
     super
-    @path         = options[:path]
-    @working_dir  = Pathname.new(File.expand_path("../", @path))
+    @path = options[:path]
   end
 
   default_task :help
@@ -28,71 +27,8 @@ class RundocCLI < Thor
   desc "build", "turns rundoc file into docs and a project"
   class_option  :path,   banner: "path/to/file.md",          optional: true, default: 'rundoc.md'
   def build
-    raise "#{@path} does not exist" unless File.exist?(@path)
-    raise "Expecting #{@path} to be a rundoc markdown file" unless File.file?(@path)
-    source_contents = File.read(@path)
-    tmp_dir         = @working_dir.join("tmp")
-
-    FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
-    tmp_dir.mkdir
-    banner = <<~HEREDOC
-      <!-- STOP
-        This file was generated by a rundoc script, do not modify it.
-
-        Instead modify the rundoc script and re-run it.
-
-        Command: #{ $0 } #{$*.join(' ')}
-      STOP -->
-    HEREDOC
-
-    puts "== Running your docs"
-    Dir.chdir(tmp_dir) do
-      @output = Rundoc::Parser.new(source_contents, Rundoc.parser_options).to_md
-      Rundoc.sanitize(@output)
-      @output = "#{banner}\n#{@output}"
-    end
-
-    puts "== Done, run was successful"
-    project_name = if Rundoc.project_root
-      Rundoc.project_root.split('/').last
-    else
-      'project'
-    end
-
-    project_dir  = @working_dir.join(project_name)
-
-    FileUtils.remove_entry_secure(project_dir) if project_dir.exist?
-
-    cp_root = if Rundoc.project_root
-      tmp_dir.join(Rundoc.project_root, ".")
-    else
-      tmp_dir.join(".")
-    end
-
-    FileUtils.cp_r(cp_root, project_dir)
-
-    FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
-
-    source_path = project_dir.join("README.md")
-    puts "== Done, writing original source to #{source_path}"
-    File.open(source_path, "w") { |f| f.write @output }
-
-    puts "== Copying source"
-    source_path = project_dir.join("coppied-#{@path.split('/').last}")
-    File.open(source_path, "w") { |f| f.write source_contents }
-
-    Dir.chdir(project_dir) do
-      Rundoc.run_after_build
-    end
-
-  ensure
-    Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
-      next unless task.alive?
-
-      puts "Warning background task is still running, cleaning up: name: #{name}"
-      task.stop
-    end
+    Rundoc::CLI.new.build(path: @path)
   end
 end
 
-RundocCLI.start(ARGV)
+RundocThorCLI.start(ARGV)

data/lib/rundoc.rb

@@ -87,3 +87,4 @@ require 'rundoc/parser'
 require 'rundoc/code_section'
 require 'rundoc/code_command'
 require 'rundoc/peg_parser'
+require 'rundoc/cli'

data/lib/rundoc/cli.rb

@@ -0,0 +1,84 @@
+module Rundoc
+  class CLI
+    def build(path: )
+      @path = Pathname.new(path).expand_path
+      raise "#{@path} does not exist" unless File.exist?(@path)
+      raise "Expecting #{@path} to be a rundoc markdown file" unless File.file?(@path)
+      @working_dir  = Pathname.new(File.expand_path("../", @path))
+
+
+      dot_env_path = File.expand_path("../.env", @path)
+      if File.exist?(dot_env_path)
+        require 'dotenv'
+        Dotenv.load(dot_env_path)
+        ENV['AWS_ACCESS_KEY_ID']     ||= ENV['BUCKETEER_AWS_ACCESS_KEY_ID']
+        ENV['AWS_REGION']            ||= ENV['BUCKETEER_AWS_REGION']
+        ENV['AWS_SECRET_ACCESS_KEY'] ||= ENV['BUCKETEER_AWS_SECRET_ACCESS_KEY']
+        ENV['AWS_BUCKET_NAME']       ||= ENV['BUCKETEER_BUCKET_NAME']
+      end
+
+      source_contents = File.read(@path)
+      tmp_dir         = @working_dir.join("tmp")
+
+      FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
+      tmp_dir.mkdir
+      banner = <<~HEREDOC
+        <!-- STOP
+          This file was generated by a rundoc script, do not modify it.
+
+          Instead modify the rundoc script and re-run it.
+
+          Command: #{ $0 } #{$*.join(' ')}
+        STOP -->
+      HEREDOC
+
+      puts "== Running your docs"
+      Dir.chdir(tmp_dir) do
+        @output = Rundoc::Parser.new(source_contents, document_path: @path).to_md
+        Rundoc.sanitize(@output)
+        @output = "#{banner}\n#{@output}"
+      end
+
+      puts "== Done, run was successful"
+      project_name = if Rundoc.project_root
+        Rundoc.project_root.split('/').last
+      else
+        'project'
+      end
+
+      project_dir  = @working_dir.join(project_name)
+
+      FileUtils.remove_entry_secure(project_dir) if project_dir.exist?
+
+      cp_root = if Rundoc.project_root
+        tmp_dir.join(Rundoc.project_root, ".")
+      else
+        tmp_dir.join(".")
+      end
+
+      FileUtils.cp_r(cp_root, project_dir)
+
+      FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
+
+      source_path = project_dir.join("README.md")
+      puts "== Done, writing original source to #{source_path}"
+      File.open(source_path, "w") { |f| f.write @output }
+
+      puts "== Copying source"
+      source_path = project_dir.join("coppied-#{@path.to_s.split('/').last}")
+      File.open(source_path, "w") { |f| f.write source_contents }
+
+      Dir.chdir(project_dir) do
+        Rundoc.run_after_build
+      end
+
+    ensure
+      Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
+        next unless task.alive?
+
+        puts "Warning background task is still running, cleaning up: name: #{name}"
+        task.stop
+      end
+    end
+  end
+end

data/lib/rundoc/code_command.rb

@@ -29,12 +29,12 @@ module Rundoc
     # Executes command to build project
     # Is expected to return the result of the command
     def call(env = {})
-      raise "not implemented"
+      raise "not implemented on #{self.inspect}"
     end
 
     # the output of the command, i.e. `$ cat foo.txt`
     def to_md(env = {})
-      raise "not implemented"
+      raise "not implemented on #{self.inspect}"
     end
   end
 end
@@ -48,3 +48,4 @@ require 'rundoc/code_command/rundoc_command'
 require 'rundoc/code_command/no_such_command'
 require 'rundoc/code_command/raw'
 require 'rundoc/code_command/background'
+require 'rundoc/code_command/website'

data/lib/rundoc/code_command/background/process_spawn.rb

@@ -1,7 +1,32 @@
 require 'shellwords'
 require 'timeout'
+require 'fileutils'
 
 class Rundoc::CodeCommand::Background
+  # This class is responsible for running processes in the background
+  #
+  # By default it logs output to a file. This can be used to "wait" for a
+  # specific output before continuing:
+  #
+  #   server = ProcessSpawn("rails server")
+  #   server.wait("Use Ctrl-C to stop")
+  #
+  # The process can be queried for it's status to check if it is still booted or not.
+  # the process can also be manually stopped:
+  #
+  #   server = ProcessSpawn("rails server")
+  #   server.alive? # => true
+  #   server.stop
+  #   server.alive? # => false
+  #
+  #
+  # There are class level methods that can be used to "name" and record
+  # background processes. They can be used like this:
+  #
+  #   server = ProcessSpawn("rails server")
+  #   ProcessSpawn.add("muh_server", server)
+  #   ProcessSpawn.find("muh_server") # => <# ProcessSpawn instance >
+  #   ProcessSpawn.find("foo") # => RuntimeError "Could not find task with name 'foo', ..."
   class ProcessSpawn
     def self.tasks
       @tasks
@@ -27,6 +52,7 @@ class Rundoc::CodeCommand::Background
 
       @log = Pathname.new(@log)
       @log.dirname.mkpath
+      FileUtils.touch(@log)
 
       @command = "/usr/bin/env bash -c #{@command.shellescape} >> #{@log} #{out}"
       @pid = nil
@@ -55,7 +81,7 @@ class Rundoc::CodeCommand::Background
 
     def stop
       return unless alive?
-      Process.kill('TERM', @pid)
+      Process.kill('TERM', -Process.getpgid(@pid))
       Process.wait(@pid)
     end
 
@@ -64,7 +90,7 @@ class Rundoc::CodeCommand::Background
     end
 
     private def call
-      @pid ||= Process.spawn(@command)
+      @pid ||= Process.spawn(@command, pgroup: true)
     end
   end
 end

data/lib/rundoc/code_command/background/start.rb

@@ -7,6 +7,7 @@ class Rundoc::CodeCommand::Background
       @name    = name
       @wait    = wait
       @allow_fail = allow_fail
+      FileUtils.touch(log)
 
       @spawn = ProcessSpawn.new(
         @command,

data/lib/rundoc/code_command/bash/cd.rb

@@ -8,11 +8,29 @@ class Rundoc::CodeCommand::Bash
       @line = line
     end
 
+    # Ignore duplicate chdir warnings "warning: conflicting chdir during another chdir block"
+    def supress_chdir_warning
+      old_stderr     = $stderr
+      capture_stderr = StringIO.new
+      $stderr        = capture_stderr
+      return yield
+    ensure
+      if old_stderr
+        $stderr = old_stderr
+        capture_string = capture_stderr.string
+        $stderr.puts capture_string if capture_string.each_line.count > 1 || !capture_string.include?("conflicting chdir")
+      end
+    end
+
     def call(env)
       line = @line.sub('cd', '').strip
       puts "running $ cd #{line}"
-      Dir.chdir(line)
-      nil
+
+      supress_chdir_warning do
+        Dir.chdir(line)
+      end
+
+      return nil
     end
   end
 end

data/lib/rundoc/code_command/no_such_command.rb

@@ -1,6 +1,10 @@
 module Rundoc
   class CodeCommand
     class NoSuchCommand < Rundoc::CodeCommand
+
+      def call(env = {})
+        raise "No such command registered with rundoc: #{@keyword.inspect} for '#{@keyword} #{@original_args}'"
+      end
     end
   end
 end

data/lib/rundoc/code_command/rundoc/depend_on.rb

@@ -0,0 +1,37 @@
+class ::Rundoc::CodeCommand
+  class RundocCommand
+    class DependOn < ::Rundoc::CodeCommand
+
+      # Pass in the relative path of another rundoc document in order to
+      # run all of it's commands (but not to )
+      def initialize(path)
+        raise "Path must be relative (i.e. start with `.` or `..`. #{path.inspect} does not" unless path.start_with?(".")
+        @path = Pathname.new(path)
+      end
+
+      def to_md(env = {})
+        ""
+      end
+
+      def call(env = {})
+        current_path = Pathname.new(env[:document_path]).dirname
+        document_path = @path.expand_path(current_path)
+        # Run the commands, but do not
+        puts "rundoc.depend_on: Start executing #{@path.to_s.inspect}"
+        output = Rundoc::Parser.new(document_path.read, document_path: document_path.to_s).to_md
+        puts "rundoc.depend_on: Done executing #{@path.to_s.inspect}, discarding intermediate document"
+        output
+      end
+
+      def hidden?
+        true
+      end
+
+      def not_hidden?
+        !hidden?
+      end
+    end
+  end
+end
+
+Rundoc.register_code_command(:"rundoc.depend_on", ::Rundoc::CodeCommand::RundocCommand::DependOn)

data/lib/rundoc/code_command/rundoc/require.rb

@@ -0,0 +1,41 @@
+class ::Rundoc::CodeCommand
+  class RundocCommand
+    class Require < ::Rundoc::CodeCommand
+
+      # Pass in the relative path of another rundoc document in order to
+      # run all of it's commands. Resulting contents will be displayed
+      # in current document
+      def initialize(path)
+        raise "Path must be relative (i.e. start with `.` or `..`. #{path.inspect} does not" unless path.start_with?(".")
+        @path = Pathname.new(path)
+      end
+
+      def to_md(env = {})
+        ""
+      end
+
+      def call(env = {})
+        env[:replace] ||= String.new
+        current_path = Pathname.new(env[:document_path]).dirname
+        document_path = @path.expand_path(current_path)
+
+        puts "rundoc.require: Start executing #{@path.to_s.inspect}"
+        output = Rundoc::Parser.new(document_path.read, document_path: document_path.to_s).to_md
+        puts "rundoc.require: Done executing #{@path.to_s.inspect}, putting contents into document"
+
+        env[:replace] << output
+        return ""
+      end
+
+      def hidden?
+        true
+      end
+
+      def not_hidden?
+        !hidden?
+      end
+    end
+  end
+end
+
+Rundoc.register_code_command(:"rundoc.require", ::Rundoc::CodeCommand::RundocCommand::Require)

data/lib/rundoc/code_command/rundoc_command.rb

@@ -19,5 +19,8 @@ module ::Rundoc
   end
 end
 
-
 Rundoc.register_code_command(:rundoc, RundocCommand)
+Rundoc.register_code_command(:"rundoc.configure", RundocCommand)
+
+require 'rundoc/code_command/rundoc/depend_on'
+require 'rundoc/code_command/rundoc/require'

data/lib/rundoc/code_command/website.rb

@@ -0,0 +1,7 @@
+class Rundoc::CodeCommand::Website
+end
+
+require 'rundoc/code_command/website/driver'
+require 'rundoc/code_command/website/screenshot'
+require 'rundoc/code_command/website/visit'
+require 'rundoc/code_command/website/navigate'

data/lib/rundoc/code_command/website/driver.rb

@@ -0,0 +1,111 @@
+require 'capybara'
+
+Capybara::Selenium::Driver.load_selenium
+
+class Rundoc::CodeCommand::Website
+  class Driver
+    attr_reader :session
+
+    def initialize(name: , url: , width: 1024, height: 720, visible: false)
+      browser_options = ::Selenium::WebDriver::Chrome::Options.new
+      browser_options.args << '--headless' unless visible
+      browser_options.args << '--disable-gpu' if Gem.win_platform?
+      browser_options.args << '--hide-scrollbars'
+      # browser_options.args << "--window-size=#{width},#{height}"
+      @width = width
+      @height = height
+
+      @driver = Capybara::Selenium::Driver.new(nil, browser: :chrome, options: browser_options)
+      driver_name = "rundoc_driver_#{name}".to_sym
+      Capybara.register_driver(driver_name) do |app|
+        @driver
+      end
+
+      @session = Capybara::Session.new(driver_name)
+    end
+
+    def visit(url)
+      @session.visit(url)
+    end
+
+    def timestamp
+      Time.now.utc.strftime("%Y%m%d%H%M%S%L%N")
+    end
+
+    def current_url
+      session.current_url
+    end
+
+    def scroll(value = 100)
+      session.execute_script "window.scrollBy(0,#{value})"
+    end
+
+    def teardown
+      session.reset_session!
+    end
+
+    def self.tasks
+      @tasks
+    end
+
+    def safe_eval(code)
+      @driver.send(:eval, code)
+    rescue => e
+      msg = String.new
+      msg << "Error running code #{code.inspect} at #{current_url.inspect}\n"
+      msg << "saving a screenshot to: `tmp/error.png`"
+      puts msg
+      session.save_screenshot("tmp/error.png")
+      raise e
+    end
+
+    def screenshot(upload: false)
+      @driver.resize_window_to(@driver.current_window_handle, @width, @height)
+      FileUtils.mkdir_p("tmp/rundoc_screenshots")
+      file_name = self.class.next_screenshot_name
+      file_path = "tmp/rundoc_screenshots/#{file_name}"
+      session.save_screenshot(file_path)
+
+      return file_path unless upload
+
+      case upload
+      when 's3', 'aws'
+        puts "Uploading screenshot to S3"
+        require 'aws-sdk-s3'
+        ENV.fetch('AWS_ACCESS_KEY_ID')
+        s3 = Aws::S3::Resource.new(region: ENV.fetch('AWS_REGION'))
+
+        key = "#{timestamp}/#{file_name}"
+        obj = s3.bucket(ENV.fetch('AWS_BUCKET_NAME')).object(key)
+        obj.upload_file(file_path)
+
+        obj.client.put_object_acl(
+          acl: 'public-read' ,
+          bucket: ENV.fetch('AWS_BUCKET_NAME'),
+          key: key
+        )
+
+        obj.public_url
+      else
+        raise "Upload #{upload.inspect} is not valid, use 's3' instead"
+      end
+    end
+
+    @tasks = {}
+    def self.add(name, value)
+      raise "Task named #{name.inspect} is already started, choose a different name" if @tasks[name]
+      @tasks[name] = value
+    end
+
+    def self.find(name)
+      raise "Could not find task with name #{name.inspect}, known task names: #{@tasks.keys.inspect}" unless @tasks[name]
+      @tasks[name]
+    end
+
+    def self.next_screenshot_name
+      @count ||= 0
+      @count += 1
+      return "screenshot_#{@count}.png"
+    end
+  end
+end