bookingit 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 175d9e2e4bc7ae8b5e306939a82fa7abaea84501
-  data.tar.gz: 7c0b21bcb5891004f1f511acd377897090e24c9b
+  metadata.gz: e51a747b5a99d2461e6864e23d34a99515061a6f
+  data.tar.gz: f70a2eae2760cab5ad9d374de574eaad4856b5c3
 SHA512:
-  metadata.gz: d1fb9e1d38399731774ec84c4361211fa36ae177d0f02a90662948b2ddf2590a2ff36fcc259b037a03e88dedc37292df03ab3e89417f4fab0f1b490b08eac782
-  data.tar.gz: ab1ae505a8b1fe697929e92d7f6968761eae1478546bd7410fda1027a8817b26188d9a31e067c0c9489c55542b9d656074a3b1bd64d8eebed88d1daee9f8de19
+  metadata.gz: c4a10173389476b2804e9c395b0f65f94deef6e308bf630057e89e282fb89e11a01e5f96cc99aa87b94aede1a22214a9ae07c2355d2e4e685d70b50d7c37714b
+  data.tar.gz: eebe9e1d025aa7bc2008c2056be4c01b013ec7f6e445a2db5f40d20d9db57dafd4a522cb770044f02efb829a0b7a355973a11bf276c766aab256855ee060ac2a

data/.gitignore

@@ -49,3 +49,4 @@ db/tmp
 spec/file-upload/stylecard-from-db.jpg
 .env
 results.html
+pkg

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    bookingit (0.0.1)
+    bookingit (0.1.0)
       gli
+      mustache
       redcarpet
 
 GEM
@@ -32,8 +33,12 @@ GEM
     gli (2.9.0)
     i18n (0.6.9)
     json (1.8.1)
+    metaclass (0.0.4)
+    mocha (1.0.0)
+      metaclass (~> 0.0.1)
     multi_json (1.8.4)
     multi_test (0.0.3)
+    mustache (0.99.5)
     rake (10.1.1)
     rdoc (4.1.1)
       json (~> 1.4)
@@ -48,5 +53,6 @@ DEPENDENCIES
   aruba
   bookingit!
   clean_test
+  mocha
   rake
   rdoc

data/README.rdoc

@@ -1,26 +1,27 @@
 = bookingit
 
-A basic publishing system that takes Mardown and a Git repository and produces a readable "book" in the following forms:
+A basic publishing system that takes Mardown and Git repositories and produces a readable "book" in the following forms:
 
 * Website
 * PDF
 * EBook
 
-The idea is to easily show the evolution of code over the course of the book, based entirely on git diffs and pull requests.
+The idea is that you can show the evolution of code by referencing particular versions or diffs beteween verions.  Further, you can show the actual output of commands run from particular verisons of the repo.
+
 
 == Example
 
+Let's say we have a Rails app locally in a git repo called "foobar".  We coudl write the following:
 
     Here is how our controller looks currently:
 
-        git:///path/to/repo.git/app/controlleres/users_controller.rb#initial-version
+        git://foobar.git/app/controlleres/users_controller.rb#initial-version
 
     We'd like to change the mailer call to use Resque
 
-        git:///path/to/repo.git/app/controllers/users_controller.rb#initial-version..add-resque-to-controller
-
+        git://foobar.git/app/controllers/users_controller.rb#initial-version..add-resque-to-controller
 
-This bit of Markdown would be interpretted as if the contents were placed inline like so:
+Instead of interpreting the code blocks as verbatim text, bookingit notices the single-line URL and will read the file or diff based on it, and substitute that into the output.  It would be the same as if we wrote our Markdown like so:
 
     Here is how our controller looks currently:
 
@@ -52,52 +53,100 @@ This bit of Markdown would be interpretted as if the contents were placed inline
         else
     ```
 
-We can also insert the output of commands:
+Here is what is currently supported:
 
-    Now, let's run our tests
+* <code>git://some_repo.git/path/in/repo.rb#sha1_or_tag</code> - show the contents of the file from the git repo at the given version (either SHA1 or tag)
+* <code>git://some_repo.git/path/in/repo.rb#sha1_or_tag..other_sha1_or_tag</code> - show a diff of the contents of the file between the two versions.
+* <code>git://some_repo.git/path/in/repo.rb#..other_sha1_or_tag</code> - shortcut for showing a diff between the given SHA1 or tag and the previous revision.
+* <code>git://some_repo.git/#sha1_or_tag!rake test</code> - check out the repo at the given SHA1 or tag, then run the command after the bang, and include the output of that command in the text
+* <code>sh:///some/filesystem/path#ls -l</code> - cd to the given path, run the command, and include its output in the text.
 
-    sh:///path/to/wherever#rake test
+The paths used can be relative (e.g. <code>git://some_repo.git</code>) or absolute (e.g. <code>git:///some/other/repo.git</code>).  Relative paths are relative to the directory where ran +bookingit+.  You can change where the git repos are located by setting +git_repos_basedir+ in your config (see below).
 
-This would be as if the output were inline like so:
+For URLs that contain shell commands, +bookingit+ will fail if the shell command fails, because the assumption is that your embedded commands are expected to succeed (exit 0).  If you need to run a shell command that is expected to fail (e.g. demonstrate a failing test case), append <code>!nonzero</code> to the URL, e.g. <code>git://some_repo.git/!rake test!nonzero</code>.  In this form, +bookingit+ will fail if the command _succeeds_.
 
+=== Configuration
 
-    Now, let's run our tests.
+The book's configuration is driven by +config.json+, which looks like so:
 
-    ```bash
-    > rake test
-    ...........................
+    {
+      "front_matter": [
+        "intro.md"
+      ],
+      "main_matter": [
+        "chapter1.md",
+        "chapter2.md"
+      ],
+      "back_matter": [
+        "appendix.md"
+      ],
+      "rendering": {
+        "stylesheets": "styles.css",
+        "git_repos_basedir": "./git_repos",
+        "languages" : {
+          ".super": "superscript",
+          "/Makefile": "make"
+        }
+      },
+      "templates": {
+        "index": "/full/path/to/index/html"
+      }
+    }
 
-    Finished in 0.00946 seconds
-    27 examples, 0 failures
+The book's contents are described in +front_matter+, +main_matter+, and +back_matter+.  The values of these can be a single file or an array of files.  The likely pattern is that you would have a single entry for +front_matter+, an array in +main_matter+ for each chapter, and an optional +back_matter+ for things like appendeces or a colophon.
 
-    Randomized with seed 43200
-    ```
+Example:
+
+    {
+      "front_matter": "intro.md"
+      "main_matter": [
+        "chapter1.md",
+        "chapter2.md",
+        "chapter3.md",
+        "chapter4.md"
+      ],
+      "back_matter": "appendix.md"
+    }
 
-== TODO
 
-Given the above, a minimal solution would be:
+The +rendering+ section allows some control over the rendering process.  It supports three keys:
 
-* Given some markdown files
-* And a configuration file
-* Be able to generate a multi-page HTML5 website with a table of contents
++git_repos_basedir+:: path to where your git repos are, for bringing in code.  For example, if you specify the value "./repos", then a url like <code>git://my_repo.git/foo/bar.rb#version-1</code> would look in <code>./repos/my_repo/foo/bar.rb</code> for the file contents.  This path should be relative to where you run +bookingit+.
++languages+:: A map of file extensions or regexps to language names for syntax detection.  If the key starts and ends with a +/+, it will be interpreted as a regexp, otherwise as a file extension
++stylesheets+:: An array of stylesheets that will be copied and linked to each HTML page
++syntax_theme+:: A highlight.js name for the syntax highlighting theme to use.
 
-=== Configuration
+The +templates+ section allows you to specify a Mustache template for various bits of the generated markup.  The files listed must be full-qualified paths and must omit the <code>.mustache</code> extension, which must be present on the file (e.g. if you specify <code>/tmp/foo.html</code>, the file should be located in <code>/tmp/foo.html.mustache</code>.
+
+Current templates are:
+
++index+:: The template of the main home page or splash page.  See the built-in one for values you have access to.
+
+In addition to values provided by bookingit, you can specify any values you want in your <code>config.json</code> file and they will be available in your templates under the +config+ namespace, e.g.:
 
-At the bare minimum the configuration file needs to indicate a structure that maps sections to markdown files.  Something like this:
 
     {
-      front_matter: [
-        "acknowledgements.md",
-        "intro.md"
-      ],
-      main_matter: [
-        "getting_started.md",
-        ["our_first_controller.md","our_first_model.md","running_tests.md"],
-        "chapter3*.md",
+      "front_matter": "intro.md"
+      "main_matter": [
+        "chapter1.md",
+        "chapter2.md",
+        "chapter3.md",
+        "chapter4.md"
       ],
-      back_matter: [
-        "glossary.md"
-      ]
+      "back_matter": "appendix.md",
+      "templates": {
+        "index": "/tmp/foo.html"
+      },
+      "title": "My Great Book!",
+      "subtitle": "A long journey from Milan to Minsk"
     }
 
-We have front, main, and back matter.  Inside each we can provide a list of files the be used in order, that represent "chapters" in that section.  A chapter can be specified either as a single file, a list of files that are subsections, or a glob.  No markup is added, this just specifies the order of processing and how to make the TOC.
+Then, in <code>/tmp/foo.html</code>
+
+    <html>
+      <body>
+        <h1>{{#config}}{{title}}{{/config}}</h1>
+        <h2>{{#config}}{{subtitle}}{{/config}}</h2>
+      </body>
+    </html>
+

data/TODO.md

@@ -0,0 +1,7 @@
+# TODO
+
+* Better TOC page
+* Better diffs
+* Ability to highlight certain lines
+* Ability to show only certain lines from a file
+* Able to keep going if things go wrong

data/bin/bookingit

@@ -20,7 +20,7 @@ command :init do |c|
 {
   "front_matter": "front.md",
   "main_matter": "main.md",
-  "back_matter": "back.md",
+  "back_matter": "back.md"
 }
 }
       end
@@ -38,64 +38,15 @@ command :init do |c|
 end
 
 desc 'build your book from markdown files'
-arg_name 'config_file output_dir'
 command :build do |c|
+  c.desc "Use cache for code samples and console sessions"
+  c.default_value true
+  c.switch :cache
   c.action do |global_options,options,args|
-    puts pwd
-    config = Bookingit::Config.new(File.read(args.shift),File.expand_path('.'))
-    output_dir = args.shift
-    mkdir output_dir unless Dir.exists?(output_dir)
-
-    renderer = Bookingit::Renderer.new
-    redcarpet = Redcarpet::Markdown.new(renderer, no_intra_emphasis: true,
-                                                             tables: true,
-                                                 fenced_code_blocks: true,
-                                                           autolink: true,
-                                                      strikethrough: true,
-                                                        superscript: true)
-
-    chdir output_dir do
-      File.open('index.html','w') do |index|
-        index.puts %{<!DOCTYPE html>
-<html>
-<head>
-</head>
-<body>
-}
-        index.puts "<ol>"
-        %w(front_matter main_matter back_matter).each do |matter|
-          index.puts "<li>#{matter}<ol>"
-          config.send(matter).chapters.each_with_index do |chapter,i|
-            contents = if chapter.path.nil?
-                      chapter.sections.map(&:path).map { |path|
-                        File.read(path)
-                      }.join("\n")
-                    else
-                      File.read(chapter.path)
-                    end
-
-            output_file = "#{matter}_#{i+1}.html"
-            File.open(output_file,'w') do |file|
-              file.puts redcarpet.render(contents)
-            end
-            title = (Array(renderer.headers[1]) +
-                     Array(renderer.headers[2]) +
-                     Array(renderer.headers[3]) +
-                     Array(renderer.headers[4]) +
-                     Array(renderer.headers[5]) +
-                     Array(renderer.headers[6])).first
-            index.puts "<li><a href='#{output_file}'>#{title}</a></li>"
-          end
-          index.puts "</ol></li>"
-        end
-        index.puts "</ol>"
-        index.puts %{
-
-</body>
-</html>
-}
-      end
-    end
+    config = Bookingit::Config.new(File.read('config.json'),File.expand_path('.'))
+    config.cache = options[:cache]
+    book = Bookingit::Book.new(config)
+    book.render_html!
   end
 end
 
@@ -107,7 +58,17 @@ post do |global,command,options,args|
 end
 
 on_error do |exception|
-  true
+  case exception
+  when Bookingit::UnexpectedShellCommandExit
+    $stderr.puts "'#{exception.command}' exited in an unexpected way with exit status #{exception.exit_code}"
+    $stderr.puts "stdout:"
+    $stderr.puts exception.stdout
+    $stderr.puts "stderr:"
+    $stderr.puts exception.stderr
+    false
+  else
+    true
+  end
 end
 
 exit run(ARGV)

data/bookingit.gemspec

@@ -20,6 +20,8 @@ spec = Gem::Specification.new do |s|
   s.add_development_dependency('rdoc')
   s.add_development_dependency('aruba')
   s.add_development_dependency('clean_test')
+  s.add_development_dependency('mocha')
   s.add_runtime_dependency('gli')
   s.add_runtime_dependency('redcarpet')
+  s.add_runtime_dependency('mustache')
 end

data/features/bookingit.feature

@@ -10,6 +10,7 @@ Feature: App does what it's supposed to do
 
 This is the introduction
     """
+    And a git repo "foobar" in "repos" containing the file "blah.rb" and a tag "some-tag"
     And the file "chapter1.md" contains:
     """
 # It Begins
@@ -18,9 +19,15 @@ This is the beginning
 
 ```
 sh:///# ls
+```
+
+And then
+
+```
+git://foobar.git/blah.rb#some-tag
 ```
     """
-    And the file "chapter2.1.md" contains:
+    And the file "chapter2.md" contains:
     """
 # The continuation
 
@@ -30,7 +37,7 @@ This is how we work
 
 Some more stuff
     """
-    And the file "chapter2.2.md" contains:
+    And the file "chapter3.md" contains:
     """
 ## Some other section
 
@@ -41,41 +48,167 @@ Even more stuff
 # Glossary
 
 This is the glossary
+    """
+    And the file "styles.css" contains:
+    """
+p, td, li {
+  font-family: 'Avenir';
+}
     """
     And this config file:
     """
 {
+  "title": "OH YEAH!",
   "front_matter": [
     "intro.md"
   ],
   "main_matter": [
     "chapter1.md",
-    "chapter2.*.md"
+    "chapter2.md",
+    "chapter3.md"
   ],
   "back_matter": [
     "appendix.md"
-  ]
+  ],
+  "rendering": {
+    "stylesheets": "styles.css",
+    "git_repos_basedir": "repos"
+  }
 }
     """
-    When I run `bookingit build config.json book`
+    When I run `bookingit build`
     Then the exit status should be 0
-    And the file "book/front_matter_1.html" should contain "This is the introduction"
-    And the file "book/main_matter_1.html" should contain "This is the beginning"
-    And the file "book/main_matter_1.html" should contain "ls"
-    And the file "book/main_matter_2.html" should contain "This is how we work"
-    And the file "book/main_matter_2.html" should contain "Even more stuff"
-    And the file "book/back_matter_1.html" should contain "This is the glossary"
-    And the file "book/index.html" should contain "front_matter_1.html"
+    And a file named "book/styles.css" should exist
+    And the file "book/intro.html" should contain "This is the introduction"
+    And the file "book/intro.html" should contain "styles.css"
+    And the file "book/chapter1.html" should contain "This is the beginning"
+    And the file "book/chapter1.html" should contain "styles.css"
+    And the file "book/chapter1.html" should contain "ls"
+    And the file "book/chapter2.html" should contain "This is how we work"
+    And the file "book/chapter3.html" should contain "Even more stuff"
+    And the file "book/chapter3.html" should contain "styles.css"
+    And the file "book/appendix.html" should contain "This is the glossary"
+    And the file "book/appendix.html" should contain "styles.css"
+    And the file "book/index.html" should contain "OH YEAH"
+    And the file "book/index.html" should contain "intro.html"
     And the file "book/index.html" should contain "My awesome book"
-    And the file "book/index.html" should contain "main_matter_1.html"
+    And the file "book/index.html" should contain "chapter1.html"
     And the file "book/index.html" should contain "It Begins"
-    And the file "book/index.html" should contain "main_matter_2.html"
+    And the file "book/index.html" should contain "chapter2.html"
     And the file "book/index.html" should contain "The continuation"
-    And the file "book/index.html" should contain "back_matter_1.html"
+    And the file "book/index.html" should contain "chapter3.html"
+    And the file "book/index.html" should contain "styles.css"
+    And the file "book/index.html" should contain "appendix.html"
     And the file "book/index.html" should contain "Glossary"
 
-    @wip
   Scenario: Init a new book
     When I run `bookingit init`
     Then a file named "config.json" should exist
 
+  Scenario: Passes through stderr/stdout of failing commands
+    Given the file "intro.md" contains:
+    """
+```
+sh:///# ls bleorgh
+```
+    """
+    And this config file:
+    """
+{
+  "front_matter": [
+    "intro.md"
+  ],
+  "main_matter": [
+    "intro.md"
+  ],
+  "back_matter": [
+    "intro.md"
+  ]
+}
+    """
+    When I run `bookingit build`
+    Then the exit status should not be 0
+    And the stderr should contain "ls bleorgh"
+    And the stderr should contain "stdout:"
+    And the stderr should contain "stderr:"
+
+  Scenario: Use my own template
+    Given the file "intro.md" contains:
+    """
+# My awesome book
+
+This is the introduction
+    """
+    And the file "chapter1.md" contains:
+    """
+# It Begins
+
+This is the beginning
+
+    """
+    And the file "/tmp/my_index.html.mustache" contains:
+    """
+<HTML>
+  <BODY>
+    <CENTER>
+      {{#config}}
+      <H1><FONT NAME='comic sans'>{{ title }}</FONT></H1>
+      <H2>{{ frob }}</H2>
+      {{/config}}
+    </CENTER>
+  </BODY>
+</HTML>
+    """
+    And this config file:
+    """
+{
+  "title": "OH YEAH!",
+  "frob": "nosticate",
+  "front_matter": [
+    "intro.md"
+  ],
+  "main_matter": [
+    "chapter1.md"
+  ],
+  "templates": {
+    "index": "/tmp/my_index.html"
+  }
+}
+    """
+    When I run `bookingit build`
+    Then the exit status should be 0
+    And the file "book/intro.html" should contain "This is the introduction"
+    And the file "book/chapter1.html" should contain "This is the beginning"
+    And the file "book/index.html" should contain "OH YEAH"
+    And the file "book/index.html" should contain "nosticate"
+
+  Scenario: Init a new book
+    When I run `bookingit init`
+    Then a file named "config.json" should exist
+
+  Scenario: Passes through stderr/stdout of failing commands
+    Given the file "intro.md" contains:
+    """
+```
+sh:///# ls bleorgh
+```
+    """
+    And this config file:
+    """
+{
+  "front_matter": [
+    "intro.md"
+  ],
+  "main_matter": [
+    "intro.md"
+  ],
+  "back_matter": [
+    "intro.md"
+  ]
+}
+    """
+    When I run `bookingit build`
+    Then the exit status should not be 0
+    And the stderr should contain "ls bleorgh"
+    And the stderr should contain "stdout:"
+    And the stderr should contain "stderr:"