docdown 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c2548137fcc0b4ebb025c13d5178d8d597ba644b
+  data.tar.gz: 1a5911b45cf51cab6d2c0b6f91fa51afe112a275
+SHA512:
+  metadata.gz: 6ef2f77c978d5d01d0d4757f79c078b3a67eb2c796188e36aa91e670f83ae610ac63d5068d83d59182f33af4e04b64bf5594a1848bb77e118fe0c61710d77082
+  data.tar.gz: 558c52df2dd318be7a675c6018a41a31fc986eaea8bda4a8111454431e44d56ed02802cc799e166e09437e5ab274249c0a3f272ac68a82671a6cb93788ce1216

data/.gitignore

@@ -0,0 +1 @@
+test/fixtures/project/

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,38 @@
+PATH
+  remote: .
+  specs:
+    heroku_docdown (0.0.1)
+      repl_runner
+      thor
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (4.0.0)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    atomic (1.1.14)
+    i18n (0.6.5)
+    metaclass (0.0.1)
+    minitest (4.7.5)
+    mocha (0.14.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.8.0)
+    rake (10.1.0)
+    repl_runner (0.0.2)
+      activesupport
+    thor (0.18.1)
+    thread_safe (0.1.3)
+      atomic
+    tzinfo (0.3.37)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  heroku_docdown!
+  mocha
+  rake

data/README.md

@@ -0,0 +1,126 @@
+## Docdown
+
+## What
+
+Write your code/docs once, don't repeat yourself. Changes/updates to docs are guaranteed to match your project
+
+## Why
+
+I wrote a Rails course, that required I build an app and write
+documentation for building said app. Wouldn't it be cool if instead
+while I write the documentation I could automate the building of my
+app?
+
+Totally! That's this, this is that thing.
+
+Write docs that build software.
+
+Why docs to code and not code to docs? Code is hard, cold and machine runnable. Docs are soft, consumed by people, and need high flexability. It's easier to explicitly tell the machine what code you want generated, then to go the other way.
+
+## Install
+
+For now this software is distributed as a rubygem. Install it manually:
+
+```
+$ gem install docdown
+```
+
+or add it to your Gemfile:
+
+```
+gem 'docdown`
+```
+
+## Use It
+
+Run the docdown command on any makdown file
+
+```sh
+  $ docdown build my_file.md
+```
+
+This will generate a project folder with your project in it, and a markdown README.md with the parsed output of the markdown docs.
+
+## Write it
+
+Docdown uses github flavored markdown and the html-pipeline behind
+the scenes. This means you write like normal but in your code sections
+you can add special annotations that when run through docdown can
+generate a project.
+
+All docdown commands are prefixed with three colons `:::` and are inclosed in a code block a
+command such as `$` which is an alias for `bash` commands like this:
+
+    ```
+    ::: $ git init .
+    ```
+
+Nothing before the three colons matters. The space between the colons
+and the command is optional.
+
+If you don't want the command to output to your markdown document you
+can add a minus symbol `-` to the end to prevent it from being
+rendered.
+
+    ```
+    :::- $ git init .
+    ```
+
+If you want the output of the actual command to be rendered to
+the screen you can use an equal sign so that
+
+    ```
+    :::= $ ls
+    ```
+
+Might generate an output something like this to your markdown doc:
+
+    ```
+    $ ls
+        Gemfile   README.rdoc app   config.ru doc   log   script    tmp
+        Gemfile.lock  Rakefile  config    db    lib   public    test    vendor
+    ```
+
+That's how you manipulate the shell with docdown, let's take a look at manipulating code.
+
+
+## Files
+
+Right now you can only write to files. Use the `write` keyword followed by a filename, on the next line(s) put the contents of the file
+
+    ```
+    ::: write config/routes.rb
+
+    Example::Application.routes.draw do
+      root        :to => "pages#index"
+
+      namespace :users do
+        resources :after_signup
+      end
+    end
+    ```
+
+If you wanted to change `users` to `products` you would write to the same file again.
+
+    ```
+    ::: write config/routes.rb
+    Example::Application.routes.draw do
+      root        :to => "pages#index"
+
+      namespace :products do
+        resources :after_signup
+      end
+    end
+    ```
+
+To delete files use bash `$` command.
+
+
+
+## TODO
+
+- Debug output
+- Fail and exit on non zero exit code
+- Breakpoints?
+- Bash commands with side effects (cd; pwd; on different lines should actually change working directory)
+- Better line matching for backtrace

data/Rakefile

@@ -0,0 +1,16 @@
+# encoding: UTF-8
+require 'bundler/gem_tasks'
+
+require 'docdown'
+
+require 'rake'
+require 'rake/testtask'
+
+task :default => [:test]
+
+test_task = Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end

data/bin/docdown

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+unless File.respond_to? :realpath
+  class File #:nodoc:
+    def self.realpath path
+      return realpath(File.readlink(path)) if symlink?(path)
+      path
+    end
+  end
+end
+$: << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
+
+require 'docdown'
+require 'thor'
+
+class DocdownCLI < Thor
+
+  def initialize(*args)
+    super
+    @config = options[:config]
+    @path   = options[:path]
+    load("./#{@config}") if @config && File.exist?(@config)
+  end
+
+  default_task :help
+
+  desc "build", "turns docdown file into docs and a project"
+  class_option  :path,   banner: "path/to/file.md",           optional: true, default: 'docdown.md'
+  class_option  :config, banner: "path/to/docdown_config.rb", default: 'docdown.rb'
+  def build
+
+    raise "#{@path} does not exist"   unless File.exist?(@path)
+    contents = File.read(@path)
+    dir      = File.expand_path("../project", @path)
+
+    FileUtils.remove_entry_secure(dir) if Dir.exist?(dir)
+    FileUtils.mkdir_p(dir)
+
+    Dir.chdir(dir) do
+      @output = Docdown::Parser.new(contents).to_md
+    end
+    File.open("README.md", "w") {|f| f.write @output }
+  end
+
+end
+
+DocdownCLI.start(ARGV)

data/docdown.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'docdown/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "docdown"
+  gem.version       = Docdown::VERSION
+  gem.authors       = ["Richard Schneeman"]
+  gem.email         = ["richard.schneeman+rubygems@gmail.com"]
+  gem.description   = %q{docdown turns docs to runable code}
+  gem.summary       = %q{docdown generates runable code from docs}
+  gem.homepage      = "https://github.com/schneems/docdown"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+
+  gem.add_dependency "thor"
+  gem.add_dependency "repl_runner"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "mocha"
+end
+

data/lib/docdown.rb

@@ -0,0 +1,37 @@
+require 'fileutils'
+
+require 'docdown/version'
+
+module Docdown
+  extend self
+
+  def code_command_from_keyword(keyword, *args)
+    klass      = code_command(keyword.to_sym)
+    cc         = klass.new(*args)
+    cc.keyword = keyword
+    cc
+  end
+
+  def code_lookup
+    @code_lookup ||= {}
+  end
+
+  def code_command(keyword)
+    code_lookup[:"#{keyword}"] || Docdown::CodeCommands::NoSuchCommand
+  end
+
+  def known_commands
+    code_lookup.keys
+  end
+
+  def register_code_command(keyword, klass)
+    code_lookup[keyword] = klass
+  end
+
+  def configure(&block)
+    yield self
+  end
+end
+
+require 'docdown/parser'
+require 'docdown/code_command'

data/lib/docdown/code_command.rb

@@ -0,0 +1,37 @@
+module Docdown
+  class CodeCommand
+    attr_accessor :hidden, :render_result, :command, :contents, :keyword
+
+    alias :hidden? :hidden
+    alias :render_result? :render_result
+
+    def initialize(arg)
+
+    end
+
+    # returns the markedup command
+    # do not over-write unless you call super
+    def render
+      result = self.call
+      return [to_md, result].join("\n")  if render_result?
+      return "" if hidden?
+      to_md
+    end
+
+    def push(contents)
+      @contents ||= ""
+      @contents << contents
+    end
+    alias :<< :push
+
+    # executes command to build project
+    def call
+      raise "not implemented"
+    end
+  end
+end
+
+require 'docdown/code_commands/bash'
+require 'docdown/code_commands/write'
+require 'docdown/code_commands/repl'
+require 'docdown/code_commands/no_such_command'

data/lib/docdown/code_commands/bash.rb

@@ -0,0 +1,23 @@
+module Docdown
+  module CodeCommands
+    class Bash < Docdown::CodeCommand
+      def initialize(command)
+        @command     = command
+        @contents = ""
+      end
+
+      def call
+        puts "Executing: #{to_md.inspect}"
+        `#{@command} #{contents} 2>&1`
+      end
+
+      def to_md
+        "$ #{@command} #{contents}"
+      end
+    end
+  end
+end
+
+
+Docdown.register_code_command(:bash, Docdown::CodeCommands::Bash)
+Docdown.register_code_command(:'$',  Docdown::CodeCommands::Bash)

data/lib/docdown/code_commands/no_such_command.rb

@@ -0,0 +1,6 @@
+module Docdown
+  module CodeCommands
+    class NoSuchCommand < Docdown::CodeCommand
+    end
+  end
+end

data/lib/docdown/code_commands/repl.rb

@@ -0,0 +1,38 @@
+require 'repl_runner'
+
+module Docdown
+  module CodeCommands
+    class Repl < Docdown::CodeCommand
+      def initialize(command)
+        @command     = command
+        @contents = ""
+      end
+
+      def keyword=(keyword)
+        @keyword = keyword
+        puts keyword
+        if keyword.to_s == "repl"
+          command_array = @command.split(" ")
+          puts command_array.inspect
+          @keyword      = command_array.first
+        else
+          @command = "#{keyword} #{@command}"
+        end
+      end
+
+      def call
+        puts @contents.inspect
+        zip = ReplRunner.new(:"#{keyword}", @command).zip(contents.strip)
+        @result = zip.flatten.join("\n")
+      end
+
+      def to_md
+        "$ #{@command}"
+      end
+    end
+  end
+end
+
+
+Docdown.register_code_command(:repl, Docdown::CodeCommands::Repl)
+Docdown.register_code_command(:irb,  Docdown::CodeCommands::Repl)

data/lib/docdown/code_commands/write.rb

@@ -0,0 +1,27 @@
+module Docdown
+  module CodeCommands
+    class Write < Docdown::CodeCommand
+      def initialize(filename)
+        @filename = filename
+        @dir      = File.expand_path("../", @filename)
+      end
+
+      # todo diff file if it already exists
+      def to_md
+        "In file `#{@filename}` add:\n#{contents}"
+      end
+
+      def call
+        puts "writing to : #{@filename}"
+        FileUtils.mkdir_p(@dir)
+        File.open(@filename, "w") do |f|
+          f.write(contents)
+        end
+        contents
+      end
+    end
+  end
+end
+
+
+Docdown.register_code_command(:write, Docdown::CodeCommands::Write)