rundoc 1.0.0 → 1.1.3

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
@@ -23,10 +48,11 @@ class Rundoc::CodeCommand::Background
     def initialize(command , timeout: 5, log: Tempfile.new("log"), out: "2>&1")
       @command = command
       @timeout_value = timeout
-      @log           = log
+      @log_reference = log # https://twitter.com/schneems/status/1285289971083907075
 
-      @log = Pathname.new(@log)
+      @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,
@@ -24,6 +25,7 @@ class Rundoc::CodeCommand::Background
     def call(env = {})
       @spawn.wait(@wait)
       @spawn.check_alive! unless @allow_fail
+
       @spawn.log.read
     end
 

data/lib/rundoc/code_command/bash.rb

@@ -32,12 +32,13 @@ class Rundoc::CodeCommand::Bash < Rundoc::CodeCommand
   end
 
   def shell(cmd, stdin = nil)
+    cmd = "(#{cmd}) 2>&1"
     msg  = "Running: $ '#{cmd}'"
     msg  << " with stdin: '#{stdin.inspect}'" if stdin && !stdin.empty?
     puts msg
 
     result = ""
-    IO.popen("#{cmd} 2>&1", "w+") do |io|
+    IO.popen(cmd, "w+") do |io|
       io << stdin if stdin
       io.close_write
       result = sanitize_escape_chars io.read
@@ -54,4 +55,4 @@ Rundoc.register_code_command(:bash, Rundoc::CodeCommand::Bash)
 Rundoc.register_code_command(:'$',  Rundoc::CodeCommand::Bash)
 Rundoc.register_code_command(:'fail.$',  Rundoc::CodeCommand::Bash)
 
-require 'rundoc/code_command/bash/cd'
+require 'rundoc/code_command/bash/cd'

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/pipe.rb

@@ -6,10 +6,7 @@ module Rundoc
       # ::: | tail -n 2
       # => "test\ntmp.file\n"
       def initialize(line)
-        line_array = line.split(" ")
-        @first     = line_array.shift.strip
-        @delegate  = Rundoc.code_command_from_keyword(@first, line_array.join(" "))
-        @delegate  = Rundoc::CodeCommand::Bash.new(line) if @delegate.kind_of?(Rundoc::CodeCommand::NoSuchCommand)
+        @delegate = parse(line)
       end
 
       # before: "",
@@ -27,6 +24,22 @@ module Rundoc
       def to_md(env = {})
         ""
       end
+
+      private def parse(code)
+        parser = Rundoc::PegParser.new.method_call
+        tree = parser.parse(code)
+        actual = Rundoc::PegTransformer.new.apply(tree)
+
+        actual = actual.first if actual.is_a?(Array)
+
+        actual = Rundoc::CodeCommand::Bash.new(code) if actual.is_a?(Rundoc::CodeCommand::NoSuchCommand)
+        return actual
+
+      # Since `| tail -n 2` does not start with a `$` assume any "naked" commands
+      # are bash
+      rescue Parslet::ParseFailed
+        Rundoc::CodeCommand::Bash.new(code)
+      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)