documentary 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3ead34348f2423c01e41ed552a763454622c704a
+  data.tar.gz: 30fe4374be10722e56c6d9f24f1ed532fb51752d
+SHA512:
+  metadata.gz: 405f93a4c0352eefbc7c9f98cfaecd597a813c5413bff0803abf7f6d7b04e4d5a5a7e17ad0a57d6d564bf2c845d72a8301cc3d6b2cefee60f566e7cf4bc1c186
+  data.tar.gz: 649f53fa435e6aae7e299057340545d2488e89302ac0b233a70709414c06f347d2982d71e34cdb3620c4e53cde41c0b6ea3ea26dfacb84a9acbf0c6ea1ced143

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+*.rbc
+/pkg/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+gemspec
+
+gem 'byebug'

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    documentary (0.1.0)
+      activesupport
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    byebug (9.0.5)
+    i18n (0.7.0)
+    json (1.8.2)
+    minitest (5.4.3)
+    rake (10.3.2)
+    thread_safe (0.3.4)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  documentary!
+  minitest (~> 5.4.3)
+  rake (~> 10.3.2)
+
+BUNDLED WITH
+   1.12.5

data/README.md

@@ -0,0 +1,152 @@
+# Documentary
+
+A simple tool that will allow you to generate API runnable documentation quickly.
+
+> If you want them to RTFM, make a better FM.
+>
+> -- <cite>Kathy Sierra</cite>
+
+## Todos
+
+* [X] Build the parser
+* [X] Integration Test
+* [X] Title Blocks
+* [X] Ordering
+* [X] Resource Blocks
+* [X] Endpoint Blocks
+* [X] Introduce Generation config
+* [X] Introduce view helpers
+* [ ] CLI design
+* [ ] TOC for documentation
+* [ ] Start being more strict on specification for MD generation?
+* [ ] Create testing suite
+
+## Specification
+
+Documentary works using good old fashioned docblocks. I believe documentation for APIs should live with the code they document. Creating a documentary docblock is as simple as
+
+```
+# --- documentary
+# Docblock content in here
+# --- end
+```
+
+The contents of a documentary docblock is YAML which will generate markdown documentation.
+
+All docblocks take an order attribute. Without it documentary will build teh documentation as it finds it in the file hierarchy.
+
+### Title Blocks
+
+Title blocks are to provide important supplamentary information about the API. They are formed as follows:
+
+```
+# --- documentary
+# type: title_block
+# title: The Heading for the Title Block
+# content: >
+#   Here is the example content, using the YAML escaping character '>'.
+# --- end
+```
+
+### Resources
+
+Resource blocks let you describe the domain of your API. They are formed as follows:
+
+```
+# --- documentary
+# type: resource
+# title: The Resource Name
+# description: >
+#   A description of the resource would go in here
+# attributes:
+#   - string_attribute:
+#     required: true
+#     type: string
+# --- end
+```
+
+Attributes are formed using the attribute name as the key and specifing if they are required (validation present) and the type to be passed.
+
+### Endpoints
+
+Endpoint blocks specify the public endpoints of your API. They are formed as follows:
+
+```
+# --- documentary
+# type: endpoint
+# title: List users
+# notes: >
+#  This enpoint will list all the users.
+# verb: GET
+# endpoint: '/users'
+# example_response:
+#   page: 1
+#   total_pages: 1
+#   count: 1
+#   users:
+#     - id: 1
+#       name: Testy McTesterson
+#       email: test@email.com
+# --- end
+```
+
+Of course not all enpoints are this simple, for `GET` requests especially you may wish to pass in extra parameters for things like pagination of filtering. This is accomplished using the `params` key. Parameters take on the structure of the param name, whether it is required and any notes (example below). Better still you can provide an example request using the `example_request` key.
+
+```
+# --- documentary
+# type: endpoint
+# title: List users
+# verb: GET
+# endpoint: '/users'
+# params:
+#   - page:
+#     required: false
+#     notes: >
+#       The page desired from the set
+#   - count:
+#     required: false
+#     notes: >
+#       The number of results to return
+#   - filter:
+#     required: false
+#     notes: >
+#       The filter for a specific user to find for example: `filter=Testy`
+# example_request: >
+#   /users?filter=Testy&page=1&count=3
+# example_response:
+#   page: 1
+#   total_pages: 1
+#   count: 1
+#   users:
+#     - id: 1
+#       name: Testy McTesterson
+#       email: test@email.com
+# --- end
+```
+
+There is a common practice on create and update (`POST` and `PUT`/`PATCH`) to return an empty response body and provide the `location` (the cannonical URL) in the response header. If no `example_response` is provided documentary will simply not generate documentation for it. We do suggest for clarity you mention this in the endpoint notes.
+
+```
+# --- documentary
+# type: endpoint
+# title: Create a user
+# notes: >
+#   The body of this response will be empty.
+# information:
+#   authenticated: true
+#   response_formats: JSON, XML
+# verb: POST
+# endpoint: '/users'
+# params:
+#   - name:
+#     required: true
+#     notes: >
+#       The name of the user
+#   - email:
+#     required: true
+#     notes: >
+#       The email of the user
+# example_request: >
+#   /users?name=Testy%20McTesterson&email=test%40email.com
+# --- end
+```

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = "test/**/*_test.rb"
+end
+
+desc 'Run tests'
+task default: :test

data/bin/documentary

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'documentary/cli'
+
+Documentary::Cli.run ARGV

data/documentary.gemspec

@@ -0,0 +1,20 @@
+basedir = File.expand_path(File.dirname(__FILE__))
+require "#{basedir}/lib/documentary/version"
+
+Gem::Specification.new do |s|
+  s.name          = 'documentary'
+  s.version       = Documentary::VERSION
+  s.summary       = 'Documentary'
+  s.description   = 'Simple, useable, runnable API documentation'
+  s.authors       = ['Dave Kennedy']
+  s.email         = 'david@bangline.co.uk'
+  s.files         = `git ls-files`.split("\n")
+  s.require_path  = 'lib'
+  s.executables   = ['documentary']
+  s.homepage      = 'http://rubygems.org/gems/documentary'
+  s.license       = 'MIT'
+
+  s.add_dependency 'activesupport'
+  s.add_development_dependency 'minitest', '~> 5.4.3'
+  s.add_development_dependency 'rake', '~> 10.3.2'
+end

data/lib/default_layout.erb

@@ -0,0 +1,5 @@
+# <%= project_name %>
+
+<%= title_blocks %>
+<%= resource_blocks %>
+<%= endpoint_blocks %>

data/lib/documentary/cli.rb

@@ -0,0 +1,39 @@
+require 'optparse'
+require 'documentary'
+
+module Documentary
+  class Cli
+    def self.run(args, out=STDOUT)
+      file_glob = "./**/*.rb"
+      project_name = File.basename(Dir.getwd).split.each {|w| w.capitalize! }.join(' ')
+      output = 'api.md'
+
+      OptionParser.new do |opts|
+        opts.on("-v", "--version", "Print version number") do
+          require "documentary/version"
+          out << "Documentary #{Documentary::VERSION}\n"
+          exit
+        end
+
+        opts.on("-d", "--directory glob", "Set directory to search for docblocks") do |glob|
+          file_glob = glob
+        end
+
+        opts.on("-p", "--project project", "Set project name") do |project|
+          project_name = project
+        end
+
+        opts.on("-o", "--output output", "Set the output file") do |op|
+          output = op
+        end
+      end.parse!
+
+      files = Dir.glob(file_glob)
+      config = {
+        project: project_name,
+        op: output
+      }
+      Documentary::Generator.new(files, config).generate
+    end
+  end
+end

data/lib/documentary/docblock.rb

@@ -0,0 +1,9 @@
+module Documentary
+  class Docblock < OpenStruct
+    def initialize(hsh)
+      super(hsh)
+      self.type = self.type.to_sym
+      self.order = self.order || 9999
+    end
+  end
+end

data/lib/documentary/docblock_collection.rb

@@ -0,0 +1,33 @@
+module Documentary
+  class DocblockCollection
+    require 'forwardable'
+    extend Forwardable
+
+    def_delegators :@collection, :<<, :concat
+
+    def initialize
+      @collection = []
+    end
+
+    def title_blocks
+      fetch_subset :title_block
+    end
+
+    def resources
+      fetch_subset :resource
+    end
+
+    def endpoints
+      fetch_subset :endpoint
+    end
+
+    private
+
+      attr_reader :collection
+
+      def fetch_subset(type)
+        collection.select { |docblock| docblock.type == type }.sort_by { |block| block.order }
+      end
+
+  end
+end

data/lib/documentary/parser.rb

@@ -0,0 +1,61 @@
+module Documentary
+  class Parser
+    require 'yaml'
+
+    def initialize(path)
+      @path = path
+      @docblocks = []
+      @line_number = 0
+      begin
+        parse_file
+      rescue Psych::SyntaxError
+        raise Documentary::InvalidDocblock.new form_exception_message
+      end
+    end
+
+    attr_reader :docblocks
+
+    private
+
+      attr_reader :path
+
+      def parse_file
+        File.open(path, 'r') do |file_content|
+          in_docblock = false
+          block_body = ""
+          comment_delimeter = ""
+          file_content.readlines.each do |line|
+            line.rstrip!
+            @line_number += 1
+            if in_docblock && line.match(/---( |)end/)
+              in_docblock = false
+              yml = YAML.load(block_body)
+              self.docblocks << Docblock.new(yml)
+              block_body = ""
+            end
+
+            if line.match(/---( |)documentary/)
+              comment_delimeter = line.match(/(.+)---/)[1]
+              @current_docblock_start = @line_number
+              in_docblock = true
+            end
+
+            if in_docblock
+              if line.match(/---( |)documentary/)
+                block_body << "---\n"
+              elsif line == comment_delimeter.rstrip
+                block_body << "\n"
+              else
+                regex = /^#{comment_delimeter}/
+                block_body << "#{line.gsub(regex, '')}\n"
+              end
+            end
+          end
+        end
+      end
+
+      def form_exception_message
+        "Invalid docblock YAML in file #{path}:#{@current_docblock_start}"
+      end
+  end
+end

data/lib/documentary/version.rb

@@ -0,0 +1,3 @@
+module Documentary
+  VERSION = "0.1.0"
+end

data/lib/documentary/view/helpers.rb

@@ -0,0 +1,106 @@
+module Documentary
+  module View
+    require 'stringio'
+
+    def title_blocks
+      io = StringIO.new
+      docblocks.title_blocks.each do |title_block|
+        io.puts "## #{title_block.title}"
+        io.puts new_line
+        io.puts title_block.content
+        io.puts new_line
+      end
+      io.string
+    end
+
+    def resource_blocks
+      io = StringIO.new
+      io.puts '## Resources'
+      io.puts new_line
+      docblocks.resources.each do |resource|
+        io.puts "### #{resource.title}"
+        io.puts new_line
+        io.puts resource.description
+        io.puts new_line
+        resource_attributes(resource, io)
+      end
+      io.puts new_line
+      io.string
+    end
+
+    def endpoint_blocks
+      io = StringIO.new
+      io.puts '## Endpoints'
+      io.puts new_line
+      docblocks.endpoints.each do |endpoint|
+        io.puts "### #{endpoint.title}"
+        io.puts new_line
+        io.puts endpoint.notes if endpoint.notes
+        io.puts new_line
+        io.puts '#### Enpoint URL'
+        io.puts new_line
+        io.puts start_code_block
+        io.puts "#{endpoint.verb} #{endpoint.endpoint}"
+        io.puts end_code_block
+        if endpoint.information
+          io.puts '#### Endpoint Information'
+          io.puts new_line
+          endpoint.information.each do |key, value|
+            io.puts "* **#{key.titleize}**: #{value}"
+          end
+        end
+        if endpoint.params
+          io.puts new_line
+          io.puts '#### Parameters'
+          io.puts new_line
+          io.puts 'Name     | Required | Description'
+          io.puts '-------- | -------- | -----------'
+          endpoint.params.each do |param|
+            io.puts "#{param.keys.first} | #{param['required']} | #{param['notes'].strip}"
+          end
+        end
+        if endpoint.example_request
+          io.puts new_line
+          io.puts '#### Example Request'
+          io.puts new_line
+          io.puts start_code_block
+          io.puts "#{endpoint.verb} #{endpoint.example_request.strip}"
+          io.puts end_code_block
+        end
+        if endpoint.example_response
+          io.puts new_line
+          io.puts '#### Example Response'
+          io.puts new_line
+          io.puts start_code_block
+          io.puts JSON.pretty_generate(endpoint.example_response)
+          io.puts end_code_block
+        end
+      end
+      io.string
+    end
+
+    def code_block
+      '```'
+    end
+
+    private
+
+      def resource_attributes(resource, io)
+        io.puts '#### Attributes'
+        io.puts new_line
+        io.puts 'Name          | Type          | Required'
+        io.puts '------------- | ------------- | -----------------'
+        resource.attributes.each do |attribute|
+          io.puts "#{attribute.keys.first} | #{attribute['type'] } | #{attribute['required'] }"
+        end
+      end
+
+      def new_line
+        "\n"
+      end
+
+      alias_method :start_code_block, :code_block
+      alias_method :end_code_block, :code_block
+
+  end
+end

data/lib/documentary.rb

@@ -0,0 +1,49 @@
+module Documentary
+  require 'ostruct'
+  require 'documentary/version'
+  require 'documentary/docblock'
+  require 'documentary/docblock_collection'
+  require 'documentary/parser'
+  require 'documentary/view/helpers'
+
+  class InvalidDocblock < StandardError; end
+
+  class Generator
+    require 'erb'
+    require 'json'
+    require 'active_support/inflector'
+
+    include View
+
+    def initialize(file_tree, config={})
+      @docblocks = DocblockCollection.new
+      @file_tree = file_tree
+      @config = config
+    end
+
+    def generate
+      file_tree.each do |path|
+        parsed_file = Parser.new(path)
+        docblocks.concat parsed_file.docblocks
+        template = File.expand_path('../default_layout.erb', __FILE__)
+        erb = ERB.new(File.new(template).read, nil, '<>')
+        File.open(output_file, 'w+') do |file|
+          file.write erb.result(binding)
+        end
+      end
+    end
+
+    private
+
+      attr_reader :file_tree, :config
+      attr_accessor :docblocks
+
+      def project_name
+        config[:project]
+      end
+
+      def output_file
+        config[:op]
+      end
+  end
+end

data/test/docblock_collection_test.rb

@@ -0,0 +1,24 @@
+require 'test_helper'
+
+class Documentary::DocblockCollectionTest < MiniTest::Test
+
+  test 'dockblocks are split by type' do
+    title_block = Documentary::Docblock.new(type: 'title_block')
+    resource_block = Documentary::Docblock.new(type: 'resource')
+    endpoint_block = Documentary::Docblock.new(type: 'endpoint')
+    collection = Documentary::DocblockCollection.new
+    collection << title_block << resource_block << endpoint_block
+    assert_equal title_block, collection.title_blocks.first
+    assert_equal resource_block, collection.resources.first
+    assert_equal endpoint_block, collection.endpoints.first
+  end
+
+  test 'docblocks are sorted by order' do
+    title_block1 = Documentary::Docblock.new(type: 'title_block')
+    title_block2 = Documentary::Docblock.new(type: 'title_block', order: 99)
+    collection = Documentary::DocblockCollection.new
+    collection << title_block1 << title_block2
+    assert_equal collection.title_blocks, [title_block2, title_block1]
+  end
+
+end

data/test/docblock_test.rb

@@ -0,0 +1,21 @@
+require 'test_helper'
+
+class Documentary::DocblockTest < MiniTest::Test
+
+  test 'type is stored as a symbol' do
+    docblock = Documentary::Docblock.new({type: 'something'})
+    assert_equal :something, docblock.type
+  end
+
+  test 'the order is defaulted if not given' do
+    docblock = Documentary::Docblock.new({type: 'something'})
+    assert_equal 9999, docblock.order
+  end
+
+  test 'the order is set if given' do
+    docblock = Documentary::Docblock.new({type: 'something', order: 1})
+    assert_equal 1, docblock.order
+  end
+
+end
+

data/test/fixtures/invalid_block.txt

@@ -0,0 +1,5 @@
+# --- documentary
+# type title_block
+# content: >
+#   This is the title block.
+# --- end

data/test/fixtures/kitchen_sink.txt

@@ -0,0 +1,60 @@
+# --- documentary
+# type: title_block
+# title: Salutations
+# content: |
+#   Hello world
+# --- end
+
+// --- documentary
+// type: title_block
+// title: Salutations Again
+// content: |
+//   Hello world Again
+// --- end
+
+# --- documentary
+# type: resource
+# title: A Resource
+# description: This is a resource
+# attributes:
+#   - email:
+#     required: true
+#     type: string
+#   - another:
+#     required: no
+#     type: boolean
+# --- end
+
+# --- documentary
+# type: endpoint
+# title: List endpoint
+# notes: Some notes about the endpoint
+# information:
+#   authenticated: true
+#   response_formats: JSON
+# verb: GET
+# endpoint: '/some/path'
+# params:
+#   - page:
+#     required: false
+#     notes: >
+#       The page desired from the set
+#   - count:
+#     required: false
+#     notes: >
+#       The number of results to return
+#   - filter:
+#     required: false
+#     notes: >
+#       The filter for a specific user to find for example: `filter=Testy`
+# example_request: >
+#   /some/path?filter=Testy&page=1&count=3
+# example_response:
+#   page: 1
+#   total_pages: 1
+#   count: 1
+#   users:
+#     - id: 1
+#       name: Testy McTesterson
+#       email: test@email.com
+# --- end

data/test/fixtures/title_block.txt

@@ -0,0 +1,30 @@
+# --- documentary
+# type: title_block
+# title: Hashes
+# content: >
+#   This is the title block. With added [markdown](http://daringfireball.net/projects/markdown/syntax)
+# --- end
+
+Some other text that should be here
+
+# this is not documentary
+# nor this. end of!
+
+  We can have wierdly indented comments like the one below!
+
+  // --- documentary
+  // type: title_block
+  // title: Slashes
+  // content: >
+  //   Dont care about comment chars
+  // --- end
+
+# --- documentary
+# type: title_block
+# title: Multiple Lines
+# content: |
+#   This is the title block.
+#
+#   With multiple
+#   Significant lines
+# --- end

data/test/integration_helper.rb

@@ -0,0 +1,37 @@
+class Minitest::Test
+  def generated_docs_path
+    File.expand_path('../../api.md', __FILE__)
+  end
+
+  def generated_docs
+    @docs ||= File.read generated_docs_path
+  end
+
+  def assert_has_title_block_header(title)
+    assert_includes generated_docs, "## #{title}"
+  end
+
+  def assert_content_for_title_block(title, content)
+    assert_match /## #{title}\n\n#{content}/, generated_docs
+  end
+
+  def assert_has_resource_title
+    assert_includes generated_docs, "## Resources"
+  end
+
+  def assert_has_enpoints_title
+    assert_includes generated_docs, "## Endpoints"
+  end
+
+  def assert_has_third_level_heading(heading)
+    assert_includes generated_docs, "### #{heading}"
+  end
+
+  def assert_content_for_resource(resource, content)
+    assert_match /### #{resource}\n\n#{content}/, generated_docs
+  end
+
+  def assert_table_entry_for_resource(resource, row_content)
+    assert_match /### #{resource}[.+]#{row_content[:name]} | #{row_content[:required]} | #{row_content[:type]}/, generated_docs
+  end
+end

data/test/integration_test.rb

@@ -0,0 +1,80 @@
+require 'test_helper'
+require 'integration_helper'
+
+class Documentary::IntegrationTest < MiniTest::Test
+
+  def config
+    {
+      project: 'Test Project',
+      op: 'api.md'
+    }
+  end
+
+  setup do
+    Documentary::Generator.new([fetch_fixture('kitchen_sink.txt')], config).generate
+  end
+
+  teardown do
+    File.unlink generated_docs_path
+  end
+
+  test 'the document title is generated correctly' do
+    assert_includes generated_docs, "# #{config[:project]}"
+  end
+
+  test 'the title blocks are correctly generated' do
+    assert_has_title_block_header 'Salutations'
+  end
+
+  test 'the content of the title block is correctly generated' do
+    assert_content_for_title_block 'Salutations', "Hello world"
+  end
+
+  test 'resources are generated' do
+    assert_has_resource_title
+  end
+
+  test 'named resources are correctly generated' do
+    assert_has_third_level_heading 'A Resource'
+  end
+
+  test 'named resources descriptions are correctly generated' do
+    assert_content_for_resource 'A Resource', 'This is a resource'
+  end
+
+  test 'named resource has table of attributes' do
+    assert_table_entry_for_resource 'A Resource', {name: 'email', required: 'true', type: 'string'}
+  end
+
+  test 'endpoints are generated' do
+    assert_has_enpoints_title
+  end
+
+  test 'named enpoints are correctly generated' do
+    assert_includes generated_docs, '### List endpoint'
+  end
+
+  test 'enpoint url is generated' do
+    assert_includes generated_docs, "```\nGET /some/path\n```"
+  end
+
+  test 'endpoint information is correctly generated' do
+    assert_includes generated_docs, '* **Authenticated**: true'
+    assert_includes generated_docs, '* **Response Formats**: JSON'
+  end
+
+  test 'enpoint params are correctly generated' do
+    assert_includes generated_docs, 'page | false | The page desired from the set'
+    assert_includes generated_docs, 'count | false | The number of results to return'
+    assert_includes generated_docs, 'filter | false | The filter for a specific user to find for example: `filter=Testy`'
+  end
+
+  test 'enpoint example request is generated' do
+    assert_includes generated_docs, "```\nGET /some/path?filter=Testy&page=1&count=3\n```"
+  end
+
+  test 'enpoint example response is generated' do
+    assert_includes generated_docs, "#### Example Response\n\n```\n"
+    assert_includes generated_docs, "\"page\": 1,\n"
+  end
+end

data/test/parser_test.rb

@@ -0,0 +1,34 @@
+require 'test_helper'
+
+class Documentary::ParserTest < MiniTest::Test
+
+  test 'that docblocks will be collected from a file' do
+    file_with_title_block = fetch_fixture('title_block.txt')
+    parser = Documentary::Parser.new(file_with_title_block)
+    assert_equal 3, parser.docblocks.count
+    assert_kind_of Documentary::Docblock, parser.docblocks.first
+  end
+
+  test 'invalid docblocks will raise invalid docblock error' do
+    file_with_title_block = fetch_fixture('invalid_block.txt')
+    assert_raises Documentary::InvalidDocblock do
+      Documentary::Parser.new(file_with_title_block)
+    end
+  end
+
+  test 'invalid docblock errors will have a helpful message' do
+    file_with_title_block = fetch_fixture('invalid_block.txt')
+    begin
+      Documentary::Parser.new(file_with_title_block)
+    rescue => e
+      assert_includes e.message, 'Invalid docblock YAML in file'
+      assert_includes e.message, '/invalid_block.txt:1'
+    end
+  end
+
+  test 'other exceptions bubble up' do
+    assert_raises Errno::ENOENT do
+      Documentary::Parser.new('not_there.txt')
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,38 @@
+require 'documentary'
+require 'minitest/autorun'
+
+# Plagiarized and bastardized from Tilt, they like tests like me. :raised_hands:
+# https://github.com/rtomayko/tilt/blob/master/test/test_helper.rb
+class Minitest::Test
+  def self.setup(&block)
+    define_method :setup do
+      super(&block)
+      instance_eval(&block)
+    end
+  end
+
+  def self.teardown(&block)
+    define_method :teardown do
+      instance_eval(&block)
+      super(&block)
+    end
+  end
+
+  def self.test(name, &block)
+    define_method(test_name(name), &block)
+  end
+
+  def fetch_fixture(name)
+    File.expand_path("../fixtures/#{name}", __FILE__)
+  end
+
+  private
+
+    def self.test_name(name)
+      "test_#{sanitize_name(name).gsub(/\s+/,'_')}".to_sym
+    end
+
+    def self.sanitize_name(name)
+      name.gsub(/\W+/, ' ').strip
+    end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: documentary
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dave Kennedy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.4.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.4.3
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 10.3.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 10.3.2
+description: Simple, useable, runnable API documentation
+email: david@bangline.co.uk
+executables:
+- documentary
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/documentary
+- documentary.gemspec
+- lib/default_layout.erb
+- lib/documentary.rb
+- lib/documentary/cli.rb
+- lib/documentary/docblock.rb
+- lib/documentary/docblock_collection.rb
+- lib/documentary/parser.rb
+- lib/documentary/version.rb
+- lib/documentary/view/helpers.rb
+- test/docblock_collection_test.rb
+- test/docblock_test.rb
+- test/fixtures/invalid_block.txt
+- test/fixtures/kitchen_sink.txt
+- test/fixtures/title_block.txt
+- test/integration_helper.rb
+- test/integration_test.rb
+- test/parser_test.rb
+- test/test_helper.rb
+homepage: http://rubygems.org/gems/documentary
+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.1
+signing_key: 
+specification_version: 4
+summary: Documentary
+test_files: []