rspec-documentation 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31073f998af7b0e0f74ebd590721dc9ba5c4aa73b9ed88bf6848a77c189d7355
-  data.tar.gz: 83343ddbbd95d4e100b2675a7e72a92c5ca9df225e99454308bd2af2b078b7ae
+  metadata.gz: 1de5016a8e2e1a370ac923d9501c654c56e87e1f236f2f260ea634a8a28167b4
+  data.tar.gz: d75c74d43b80b502daa00778c3d4e8ede22514c2f500d67ee6dc31cb994772e3
 SHA512:
-  metadata.gz: e5d845f98a5ceaa7c0c6462cad990a598d84086955f61334b3011c5f3fb15d0e90cd1ba8fff75f3d1559aa8e8f841f78c16391e37a3c048bd1876916b0b352af
-  data.tar.gz: '04739b7fb732fc7a1a6492f23d12d31d598b21d769c89238d0b29aa535a1620069fbc0b1610c8d1fa3d6a29a85a8d614768167b750c3416bbe83871f8990c11b'
+  metadata.gz: 1bc358ecfcda3670c648dac2f11698facb57c2dc147826a87a26b24af07a1517fda6cd43431be25facb996280e7de50848630f0f8aab9ead11743ac1ec76e77e
+  data.tar.gz: a622ad2f53e2c743431678ed97e9a36a037c86f5b4b15c67c3eff439158ff0af026878be1f55a1aa5d4ee45b1a672a57db66c28912de012471d5bcd7aeedb6b1

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--exclude spec/fixtures/**/*_spec.rb

data/.rubocop.yml

@@ -4,3 +4,5 @@ require:
 
 AllCops:
   NewCops: enable
+  Exclude:
+  - 'spec/fixtures/**/*'

data/Gemfile

@@ -7,7 +7,10 @@ gemspec
 
 gem 'rake', '~> 13.0'
 
+gem 'devpack', '~> 0.4.1'
 gem 'rspec', '~> 3.0'
+gem 'rspec-file_fixtures', '~> 0.1.6'
+gem 'rspec-its', '~> 1.3'
 gem 'rubocop', '~> 1.51'
 gem 'rubocop-rake', '~> 0.6.0'
 gem 'rubocop-rspec', '~> 2.22'

data/Gemfile.lock

@@ -1,25 +1,41 @@
 PATH
   remote: .
   specs:
-    rspec-documentation (0.0.1)
+    rspec-documentation (0.0.2)
+      htmlbeautifier (~> 1.4)
+      kramdown (~> 2.4)
+      kramdown-parser-gfm (~> 1.1)
+      paintbrush (~> 0.1.1)
+      redcarpet (~> 3.6)
+      rouge (~> 4.1)
+      rspec (~> 3.12)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
     concurrent-ruby (1.2.2)
+    devpack (0.4.1)
     diff-lcs (1.5.0)
+    htmlbeautifier (1.4.2)
     i18n (1.13.0)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     paint (2.3.0)
+    paintbrush (0.1.1)
     parallel (1.23.0)
     parser (3.2.2.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
+    redcarpet (3.6.0)
     regexp_parser (2.8.0)
     rexml (3.2.5)
+    rouge (4.1.1)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -29,6 +45,11 @@ GEM
     rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
+    rspec-file_fixtures (0.1.6)
+      rspec (~> 3.0)
+    rspec-its (1.3.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
     rspec-mocks (3.12.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
@@ -62,13 +83,15 @@ GEM
     unicode-display_width (2.4.2)
 
 PLATFORMS
-  ruby
   x86_64-linux
 
 DEPENDENCIES
+  devpack (~> 0.4.1)
   rake (~> 13.0)
   rspec (~> 3.0)
   rspec-documentation!
+  rspec-file_fixtures (~> 0.1.6)
+  rspec-its (~> 1.3)
   rubocop (~> 1.51)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.22)

data/README.md

@@ -1,4 +1,4 @@
-# Rspec::Documentation
+# RSpec::Documentation
 
 TODO: Delete this and the text below, and describe your gem
 

data/Rakefile

@@ -2,6 +2,7 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rspec/documentation'
 
 RSpec::Core::RakeTask.new(:spec)
 

data/exe/rspec-documentation

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/rspec/documentation'
+RSpec::Documentation.generate_documentation

data/lib/rspec/documentation/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module Rspec
+module RSpec
   module Documentation
-    VERSION = '0.0.1'
+    VERSION = '0.0.2'
   end
 end

data/lib/rspec/documentation.rb

@@ -1,10 +1,73 @@
 # frozen_string_literal: true
 
 require_relative 'documentation/version'
+require_relative '../rspec_documentation'
+load File.expand_path(File.join(__dir__, '../tasks/rspec/documentation/generate.rake'))
 
-module Rspec
+module RSpec
+  # Extension for RSpec, locates RSpec examples found in a Markdown file and executes them,
+  # replacing their output into a tree of Markdown files.
   module Documentation
     class Error < StandardError; end
-    # Your code goes here...
+
+    class << self
+      include Paintbrush
+
+      def generate_documentation
+        require_spec_helper
+        page_collection.generate
+        page_collection.flush unless failed?
+        print_summary
+        nil
+      end
+
+      def require_spec_helper
+        path = Pathname.new(Dir.pwd).join('rspec-documentation/spec_helper.rb')
+        require path if path.file?
+      end
+
+      def configure(&block)
+        RSpecDocumentation.configure(&block)
+      end
+
+      private
+
+      def print_success_summary
+        warn(paintbrush { green("\n  Created #{blue(page_paths.size)} pages.\n") })
+        warn(paintbrush { cyan("  View your documentation here: #{white(bundle_index_path)}\n") })
+      end
+
+      def print_failure_summary
+        page_collection.failures.each do |failure|
+          $stderr.write(failure.message)
+        end
+      end
+
+      def bundle_index_path
+        RSpecDocumentation::Util.bundle_dir.glob('*.html').first.expand_path
+      end
+
+      def page_paths
+        @page_paths ||= Pathname.new(Dir.pwd).join('rspec-documentation/pages').glob('**/*.md')
+      end
+
+      def page_collection
+        @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
+      end
+
+      def failed?
+        !page_collection.failures.empty?
+      end
+
+      def print_summary
+        if failed?
+          print_failure_summary
+        else
+          print_success_summary
+        end
+
+        nil
+      end
+    end
   end
 end

data/lib/rspec_documentation/ansi_html.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Outputs a string containing ANSI color code escape sequences into HTML with attached classes
+  # for each matched color code. Cleans any remaining escape codes.
+  class AnsiHTML
+    COLOR_CODES = [0, 1, 2, 3, 4, 5, 6, 7, 9].freeze
+
+    def initialize(content)
+      @content = content
+    end
+
+    def render
+      "<div class='ansi-html border m-1 p-4'><span>#{subbed_content}</span></div>"
+    end
+
+    private
+
+    attr_reader :content
+
+    def subbed_content
+      COLOR_CODES.reduce(content) do |string, color_code|
+        string.gsub("\e[3#{color_code}m", "</span><span class='ansi-color-#{color_code}'>")
+              .gsub("\e[0m", "</span><span class='ansi-color-reset'>")
+      end.gsub(/\e\[[0-9]+m/, '')
+    end
+  end
+end

data/lib/rspec_documentation/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
+  class Configuration
+    def initialize
+      @context = Context.new
+    end
+
+    def context
+      yield @context if block_given?
+      @context
+    end
+  end
+end

data/lib/rspec_documentation/context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Used to fetch missing methods called in examples, provides a context available to all
+  # examples to avoid repeated setup in each example. Usage:
+  #
+  # ```ruby
+  # RSpec::Documentation.configure do |config|
+  #   config.context do |context|
+  #     context.my_value = 'example value'
+  #   end
+  # end
+  # ```
+  #
+  # `my_value` will now be available in every example.
+  class Context
+    def initialize
+      @context = {}
+    end
+
+    private
+
+    def method_missing(key, *args, &block)
+      return _assign(key, *args, &block) if key.to_s.end_with?('=')
+      return super unless @context.key?(key)
+
+      @context.fetch(key)
+    end
+
+    def respond_to_missing?(_key, *_)
+      true
+    end
+
+    def _assign(key, *args, &block)
+      key = key.to_s.rpartition('=').first.to_sym
+
+      @context[key] = if block_given?
+                        block
+                      else
+                        args.first
+                      end
+    end
+  end
+end

data/lib/rspec_documentation/document.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Translates a Markdown document into a structure of parsed Markdown and embedded RSpec examples.
+  class Document
+    attr_reader :failures, :page_tree
+
+    def initialize(document:, page_tree:)
+      @document = document
+      @page_tree = page_tree
+      @failures = []
+    end
+
+    def specs
+      @specs ||= parsed_document.specs
+    end
+
+    def render
+      parsed_document.execute_and_substitute_examples!
+      if parsed_document.failures.empty?
+        RSpecDocumentation.template('layout').result(binding)
+      else
+        failures.concat(parsed_document.failures)
+        nil
+      end
+    end
+
+    def html
+      parsed_document.html
+    end
+
+    def title
+      # TODO: Try other methods of inferring documentation title, allow setting by configuration
+      gem_spec&.name
+    end
+
+    def version
+      gem_spec&.version
+    end
+
+    def header
+      RSpecDocumentation.template('header').result(binding)
+    end
+
+    def footer
+      RSpecDocumentation.template('footer').result(binding)
+    end
+
+    private
+
+    attr_reader :document
+
+    def parsed_document
+      @parsed_document ||= ParsedDocument.new(document)
+    end
+
+    def gem_spec
+      @gem_spec ||= Gem::Specification.load(Pathname.new(Dir.pwd).glob('*.gemspec').first.to_s)
+    end
+  end
+end

data/lib/rspec_documentation/html_element.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Receives a spec manifest and generates a `Kramdown::Document` contaning an HTML node with a
+  # tabbed view displaying the example's code, its output and, if format is `:html`, the rendered
+  # HTML of the output. Injected into the parsed `Kramdown::Document` for the root Markdown file,
+  # replacing the code block it was produced from.
+  class HtmlElement
+    def initialize(spec:)
+      @spec = spec
+    end
+
+    def element
+      Kramdown::Document.new(tabbed_spec, input: 'html').root
+    end
+
+    def html_source
+      return nil unless spec.format == :html
+
+      formatter = Rouge::Formatters::HTML.new
+      lexer = Rouge::Lexers::HTML.new
+
+      formatter.format(lexer.lex(HtmlBeautifier.beautify(spec.described_object)))
+    end
+
+    def code_source
+      formatted_ruby(spec.source)
+    end
+
+    def rendered_result
+      return spec.described_object if spec.format == :html
+      return AnsiHTML.new(spec.described_object).render if spec.format == :ansi
+
+      formatted_ruby(spec.described_object.inspect)
+    end
+
+    def element_id
+      @element_id ||= SecureRandom.uuid
+    end
+
+    private
+
+    attr_reader :spec
+
+    def tabbed_spec
+      RSpecDocumentation.template('tabbed_spec').result(binding)
+    end
+
+    def formatted_ruby(code)
+      formatter = Rouge::Formatters::HTML.new
+      lexer = Rouge::Lexers::Ruby.new
+      formatter.format(lexer.lex(code))
+    end
+  end
+end

data/lib/rspec_documentation/markdown_renderer.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    include Rouge::Plugins::Redcarpet
+  end
+end

data/lib/rspec_documentation/page_collection.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Builds content for a collection of page paths, collates failures from embedded examples.
+  # Writes the final structure to disk.
+  class PageCollection
+    attr_reader :failures
+
+    def initialize(page_paths:)
+      @page_paths = page_paths
+      @buffer = {}
+      @failures = []
+    end
+
+    def generate
+      page_paths.sort.each do |path|
+        document = Document.new(document: path.read, page_tree: page_tree)
+        buffer[bundle_path_for(path)] = document.render
+        @failures.concat(document.failures)
+      end
+    end
+
+    def flush
+      Util.bundle_dir.rmtree if Util.bundle_dir.directory?
+      Util.bundle_dir.mkpath
+
+      @buffer.each do |path, content|
+        path.dirname.mkpath
+        Util.bundle_path(path).write(content)
+      end
+    end
+
+    private
+
+    attr_reader :page_paths, :buffer
+
+    def page_tree
+      PageTree.new(page_paths: page_paths)
+    end
+
+    def bundle_path_for(path)
+      Util.bundle_path(path)
+    end
+
+    def root_path
+      Pathname.new(Dir.pwd).join('rspec-documentation')
+    end
+  end
+end

data/lib/rspec_documentation/page_tree.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # A hierarchical structure of all pages in the documentation tree. Used for rendering a navigation section.
+  class PageTree
+    def initialize(page_paths:)
+      @page_paths = page_paths
+      @structure = {}
+      @nodes = []
+    end
+
+    def elements
+      build_nodes(
+        root: tree['rspec-documentation']['pages'],
+        path: root_path.join('rspec-documentation/pages')
+      )
+      nodes.flatten.compact
+    end
+
+    private
+
+    attr_reader :page_paths, :structure, :nodes
+
+    def tree
+      @tree ||= begin
+        build_tree
+        structure
+      end
+    end
+
+    def build_nodes(root:, path:)
+      root[:children].sort.map do |child|
+        node = page_tree_node(path: path, child: child)
+        next nil if node.nil?
+
+        nodes.concat(node)
+        nodes.push('<ul>')
+        build_nodes(root: root[child], path: path.join(child)) unless root[child].nil?
+        nodes.push('</ul>')
+      end
+    end
+
+    def build_tree(branch: structure, depth: 0)
+      normalized_paths.each do |path|
+        first, second, *rest = path_segments(path: path, depth: depth)
+        next if second.nil?
+
+        branch[first] ||= {}
+        branch[first][:children] ||= Set.new
+        branch[first][:children].add(second)
+        build_tree(branch: branch[first], depth: depth + 1)
+      end
+    end
+
+    def path_segments(path:, depth:)
+      path.to_s.split('/')[depth..]
+    end
+
+    def root_path
+      @root_path ||= Pathname.new(Dir.pwd)
+    end
+
+    def normalized_paths
+      @normalized_paths ||= page_paths.sort.map do |path|
+        path.relative_path_from(root_path)
+      end
+    end
+
+    def page_tree_node(path:, child:)
+      PageTreeElement.new(path: path, child: child).node
+    end
+  end
+end

data/lib/rspec_documentation/page_tree_element.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # An element in a page tree, generates a single entry as a list item, linked to the relevant
+  # document (or just a text entry if no document exists, i.e. if it is a directory without an
+  # index file).
+  class PageTreeElement
+    def initialize(path:, child:)
+      @path = path
+      @child = child
+      @nodes = []
+    end
+
+    def node
+      return nil if entry_and_directory?
+
+      nodes.push('<li>')
+      nodes.push(link) if entry?
+      nodes.push(bullet) unless entry?
+      nodes.push('</li>')
+      nodes
+    end
+
+    private
+
+    attr_reader :path, :child, :nodes
+
+    def entry_and_directory?
+      return false unless path.join(child).sub_ext('.md').file?
+      return false unless path.join(child).sub_ext('').directory?
+      return false unless path.join(child).file?
+
+      true
+    end
+
+    def entry?
+      path.join(child).sub_ext('.md').file?
+    end
+
+    def link
+      "<a href='#{href}'>#{title}</a>"
+    end
+
+    def bullet
+      "<b>#{title}</b>"
+    end
+
+    def href
+      Util.href(path.join(child))
+    end
+
+    def title
+      Util.label(child)
+    end
+  end
+end

data/lib/rspec_documentation/parsed_document.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # A parsed Markdown file, provides matched RSpec examples from the document and their location.
+  class ParsedDocument
+    attr_reader :failures
+
+    def initialize(document)
+      @document = Kramdown::Document.new(document, input: 'GFM')
+      @failures = []
+    end
+
+    def html
+      document.to_html
+    end
+
+    def execute_and_substitute_examples!
+      specs.each do |spec|
+        spec.run
+        break failures << spec.failure unless spec.failure.nil?
+
+        spec.parent.children[spec.index] = spec_element(spec)
+      end
+    end
+
+    def specs
+      @specs ||= recursive_specs
+    end
+
+    private
+
+    attr_reader :document
+
+    def recursive_specs(element: document.root)
+      element.children.each.with_index.map do |child, index|
+        next recursive_specs(element: child) unless child.children.empty?
+        next nil unless rspec_codeblock?(child)
+
+        spec_for(element: child, parent: element, index: index)
+      end.flatten.compact
+    end
+
+    def rspec_codeblock?(element)
+      return false unless element.type == :codeblock
+      return false unless element.options.key?(:lang)
+
+      element.options[:lang] == 'rspec' || element.options[:lang].start_with?('rspec:')
+    end
+
+    def spec_for(element:, parent:, index:)
+      Spec.new(
+        spec: element.value,
+        format: element.options[:lang].partition(':').last,
+        parent: parent,
+        index: index,
+        location: element.options[:location]
+      )
+    end
+
+    def spec_element(spec)
+      Kramdown::Element.new(:html_element, 'div', { location: spec.location }).tap do |element|
+        element.children = HtmlElement.new(spec: spec).element.children
+      end
+    end
+
+    def report_error(spec)
+      $stderr.write(spec.failure.message)
+    end
+  end
+end