rspec-documentation 0.0.2 → 0.0.4

data/lib/rspec_documentation/page_collection.rb

@@ -4,19 +4,24 @@ 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
+    attr_reader :failures, :page_paths
 
     def initialize(page_paths:)
-      @page_paths = page_paths
+      @page_paths = page_paths.sort
       @buffer = {}
       @failures = []
     end
 
     def generate
-      page_paths.sort.each do |path|
-        document = Document.new(document: path.read, page_tree: page_tree)
+      page_paths.zip(documents).each do |path, document|
         buffer[bundle_path_for(path)] = document.render
-        @failures.concat(document.failures)
+        failures.concat(document.failures)
+      end
+    end
+
+    def documents
+      @documents ||= page_paths.map do |path|
+        Document.new(document: path.read, path: path, page_tree: page_tree(path: path))
       end
     end
 
@@ -24,18 +29,28 @@ module RSpecDocumentation
       Util.bundle_dir.rmtree if Util.bundle_dir.directory?
       Util.bundle_dir.mkpath
 
-      @buffer.each do |path, content|
+      buffer.each do |path, content|
         path.dirname.mkpath
         Util.bundle_path(path).write(content)
       end
+      write_index unless buffer.empty?
+    end
+
+    def examples_count
+      documents.map(&:specs).flatten.size
     end
 
     private
 
-    attr_reader :page_paths, :buffer
+    attr_reader :buffer
+
+    def write_index
+      _path, content = buffer.first
+      Util.bundle_index_path.write(content)
+    end
 
-    def page_tree
-      PageTree.new(page_paths: page_paths)
+    def page_tree(path:)
+      PageTree.new(page_paths: page_paths, current_path: path)
     end
 
     def bundle_path_for(path)

data/lib/rspec_documentation/page_tree.rb

@@ -3,8 +3,9 @@
 module RSpecDocumentation
   # A hierarchical structure of all pages in the documentation tree. Used for rendering a navigation section.
   class PageTree
-    def initialize(page_paths:)
+    def initialize(page_paths:, current_path:)
       @page_paths = page_paths
+      @current_path = current_path
       @structure = {}
       @nodes = []
     end
@@ -19,7 +20,7 @@ module RSpecDocumentation
 
     private
 
-    attr_reader :page_paths, :structure, :nodes
+    attr_reader :page_paths, :structure, :nodes, :current_path
 
     def tree
       @tree ||= begin
@@ -29,17 +30,24 @@ module RSpecDocumentation
     end
 
     def build_nodes(root:, path:)
-      root[:children].sort.map do |child|
+      root[:children].sort.each 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>')
+        li_open, *li_body, li_close = node
+        nodes.push(li_open)
+        nodes.concat(li_body)
+        push_children(root: root, path: path, child: child)
+        nodes.push(li_close)
       end
     end
 
+    def push_children(root:, path:, child:)
+      nodes.push('<ol>')
+      build_nodes(root: root[child], path: path.join(child)) unless root[child].nil?
+      nodes.last == '<ol>' ? nodes.pop : nodes.push('</ol>')
+    end
+
     def build_tree(branch: structure, depth: 0)
       normalized_paths.each do |path|
         first, second, *rest = path_segments(path: path, depth: depth)
@@ -67,7 +75,7 @@ module RSpecDocumentation
     end
 
     def page_tree_node(path:, child:)
-      PageTreeElement.new(path: path, child: child).node
+      PageTreeElement.new(path: path, child: child, current_path: current_path).node
     end
   end
 end

data/lib/rspec_documentation/page_tree_element.rb

@@ -5,25 +5,26 @@ module RSpecDocumentation
   # 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:)
+    def initialize(path:, child:, current_path:)
       @path = path
       @child = child
+      @current_path = current_path
       @nodes = []
+      raise MissingFileError, "Missing file: #{entry_path.relative_path_from(Util.base_dir)}" unless entry?
     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_open)
+      nodes.push(link)
       nodes.push('</li>')
       nodes
     end
 
     private
 
-    attr_reader :path, :child, :nodes
+    attr_reader :path, :child, :current_path, :nodes
 
     def entry_and_directory?
       return false unless path.join(child).sub_ext('.md').file?
@@ -33,22 +34,43 @@ module RSpecDocumentation
       true
     end
 
+    def entry_path
+      path.join(child).sub_ext('.md')
+    end
+
     def entry?
-      path.join(child).sub_ext('.md').file?
+      entry_path.file?
+    end
+
+    def li_open
+      "<li id='#{Util.path_id(path.join(child))}' #{active_class} data-list-item-id='##{path_id}' " \
+        "data-parent-id='##{parent_path_id}'>"
     end
 
     def link
-      "<a href='#{href}'>#{title}</a>"
+      "<a #{active_class} href='#{href}'>#{title}</a>"
+    end
+
+    def path_id
+      @path_id ||= Util.path_id(path.join(child))
+    end
+
+    def parent_path_id
+      @parent_path_id ||= Util.path_id(path)
     end
 
-    def bullet
-      "<b>#{title}</b>"
+    def active_class
+      active? ? 'class="active"' : nil
     end
 
     def href
       Util.href(path.join(child))
     end
 
+    def active?
+      Util.href(current_path) == href
+    end
+
     def title
       Util.label(child)
     end

data/lib/rspec_documentation/parsed_document.rb

@@ -5,8 +5,9 @@ module RSpecDocumentation
   class ParsedDocument
     attr_reader :failures
 
-    def initialize(document)
-      @document = Kramdown::Document.new(document, input: 'GFM')
+    def initialize(document, path:)
+      @document = Kramdown::Document.new(document, input: 'GFM', syntax_highlighter: 'rouge')
+      @path = path
       @failures = []
     end
 
@@ -29,7 +30,7 @@ module RSpecDocumentation
 
     private
 
-    attr_reader :document
+    attr_reader :document, :path
 
     def recursive_specs(element: document.root)
       element.children.each.with_index.map do |child, index|
@@ -53,6 +54,7 @@ module RSpecDocumentation
         format: element.options[:lang].partition(':').last,
         parent: parent,
         index: index,
+        path: path,
         location: element.options[:location]
       )
     end

data/lib/rspec_documentation/project_initialization.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Initializes a new project if `rspec-documentation/` directory is empty.
+  class ProjectInitialization
+    include Paintbrush
+
+    def flush
+      print_welcome
+      create_base_dir
+      create_sample_files
+      print_initialization_complete
+    end
+
+    private
+
+    def print_welcome
+      warn(paintbrush { blue "\nWelcome to #{cyan 'RSpec Documentation'}. A new project is being initialized.\n" })
+      warn(paintbrush { blue "If you want undo at any point, simply delete #{cyan 'rspec-documentation/'}.\n" })
+    end
+
+    def create_base_dir
+      Util.base_dir.mkpath
+      print_created(Util.base_dir)
+    end
+
+    def create_sample_files
+      sample_files.each do |sample_file|
+        Util.base_dir.join(sample_file).sub_ext('.md').write(RSpecDocumentation.template(sample_file, :md).result)
+        print_created(Util.base_dir.join(sample_file).sub_ext('.md'))
+      end
+    end
+
+    def print_created(path)
+      warn(paintbrush { "   #{green_b 'create'} #{cyan path.relative_path_from(pwd)}" })
+    end
+
+    def print_initialization_complete
+      warn(paintbrush do
+        blue "\nYour documentation project has been #{green 'initialized'} wlth smoe example pages."
+      end)
+    end
+
+    def pwd
+      Pathname.new(Dir.pwd)
+    end
+
+    def sample_files
+      %w[000-Introduction 010-Usage 500-License]
+    end
+  end
+end

data/lib/rspec_documentation/rspec/failure.rb

@@ -4,34 +4,49 @@ module RSpecDocumentation
   module RSpec
     # Stores information about a failed RSpec example. Thin wrapper around `RSpec::Failure`.
     class Failure
+      include Paintbrush
+
+      attr_reader :spec
+
       def initialize(cause:, spec:)
         @cause = cause
         @spec = spec
       end
 
       def message
-        "\n#{formatted_header}\n\n#{formatted_source}\n#{formatted_cause}\n\n"
+        "\n#{formatted_header}\n\n#{formatted_source}\n\n#{formatted_cause}\n\n"
       end
 
       private
 
-      attr_reader :cause, :spec
+      attr_reader :cause
 
       def formatted_header
-        "\e[1;37m#{indented('Failure in example')}:\e[0m"
+        paintbrush { cyan indented("# #{path}:#{spec.location}") }
+      end
+
+      def path
+        spec.path.relative_path_from(Pathname.new(Dir.pwd))
       end
 
       def formatted_source
-        "\e[1;34m#{indented(spec.source)}\e[0m"
+        paintbrush { white indented(spec.source) }
       end
 
       def formatted_cause
-        "\e[31m#{indented(cause.message)}\e[0m"
+        paintbrush { red indented(without_anonymous_group_text(cause.message)) }
       end
 
       def indented(text)
         text.split("\n").map { |line| "    #{line}" }.join("\n")
       end
+
+      # If an error occurs outside of a test, RSpec will provide an error to the Reporter
+      # referring to an anonymous group due to the way specs are evaluated. This does not help
+      # with debugging so we remove it. TODO: Find a better way ?
+      def without_anonymous_group_text(text)
+        text&.gsub(/ for #<RSpec::ExampleGroups::Anonymous.*$/, '')
+      end
     end
   end
 end

data/lib/rspec_documentation/rspec.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'rspec/example_group'
-require_relative 'rspec/reporter'
 require_relative 'rspec/failure'
 
 module RSpecDocumentation

data/lib/rspec_documentation/spec.rb

@@ -3,20 +3,30 @@
 module RSpecDocumentation
   # Executes specs from a Markdown code block and provides the outcome in the appropriate format.
   class Spec
-    attr_reader :parent, :location, :index, :format
+    attr_reader :parent, :location, :index, :format, :path
 
-    def initialize(spec:, format:, parent:, location:, index:)
+    @durations = []
+
+    class << self
+      attr_accessor :subjects, :durations
+    end
+
+    def initialize(spec:, format:, parent:, location:, path:, index:) # rubocop:disable Metrics/ParameterLists
       @spec = spec
       @format = format.empty? ? :plaintext : format.to_sym
       @parent = parent
       @location = location
+      @path = path
       @index = index
       @failures = []
-      @reporter = RSpec::Reporter.new
     end
 
-    def described_object
-      @described_object ||= reporter.described_object
+    def subject
+      raise Error, "Code block did not define an example (e.g. with `it`).\n#{spec}" if examples.empty?
+      raise Error, "Code block did not define a subject:\n#{spec}" if subjects.empty?
+      raise Error, "Cannot define more than one example per code block:\n#{spec}" if subjects.size > 1
+
+      subjects.last
     end
 
     def source
@@ -27,15 +37,33 @@ module RSpecDocumentation
       failures.first
     end
 
+    def reporter
+      @reporter ||= ::RSpec::Core::Reporter.new(::RSpec::Core::Configuration.new)
+    end
+
     def run
+      self.class.subjects = []
       RSpec.with_failure_notifier(failure_notifier) do
-        example_group.run(reporter)
+        succeeded = example_group.run(reporter)
+        durations << run_time if run_time
+        next succeeded if succeeded
+
+        notify_failure(reported_failure)
+        succeeded
       end
     end
 
     private
 
-    attr_reader :spec, :failures, :reporter
+    attr_reader :spec, :failures
+
+    def subjects
+      self.class.subjects
+    end
+
+    def durations
+      self.class.durations
+    end
 
     def examples
       @examples ||= example_group.examples
@@ -45,18 +73,36 @@ module RSpecDocumentation
       # rubocop:disable Style/DocumentDynamicEvalDefinition, Security/Eval
       @example_group ||= binding.eval(
         <<-SPEC, __FILE__, __LINE__.to_i
-          RSpec::ExampleGroup.describe do
-            #{spec}
+          ::RSpec::Core::ExampleGroup.describe do
+            after { RSpecDocumentation::Spec.subjects << subject }
+            include_context '__rspec_documentation' do
+              #{spec}
+            end
           end
         SPEC
       )
       # rubocop:enable Style/DocumentDynamicEvalDefinition, Security/Eval
     end
 
+    def run_time
+      return nil unless reporter&.examples&.first
+
+      @run_time ||= reporter.examples.first.execution_result.run_time
+    end
+
+    def notify_failure(failure)
+      failures << RSpec::Failure.new(cause: failure, spec: self)
+    end
+
+    def reported_failure
+      exception = reporter.failed_examples.first.exception
+      return exception unless exception.is_a?(::RSpec::Core::MultipleExceptionError)
+
+      exception.all_exceptions.first
+    end
+
     def failure_notifier
-      proc do |failure|
-        failures << RSpec::Failure.new(cause: failure, spec: self)
-      end
+      proc { |failure| notify_failure(failure) }
     end
   end
 end

data/lib/rspec_documentation/stylesheet_bundle.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Compiles CSS assets into a single file.
+  class StylesheetBundle
+    def flush
+      Util.bundle_dir.join('assets').mkpath
+      stylesheet_bundle_path.write(RSpecDocumentation.template(:layout, :css).result(binding))
+    end
+
+    private
+
+    def stylesheet_bundle_path
+      Util.bundle_dir.join('assets/bundle.css')
+    end
+  end
+end

data/lib/rspec_documentation/summary.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Provides a summary of the test run including details of any failures.
+  class Summary
+    include Paintbrush
+
+    def initialize(page_collection:, pwd:, started_at:)
+      @page_collection = page_collection
+      @pwd = pwd
+      @duration = Time.now.utc - started_at
+    end
+
+    def flush
+      if page_collection.failures.empty?
+        print_success_summary
+      else
+        print_failure_summary
+      end
+
+      print_duration_summary
+
+      nil
+    end
+
+    private
+
+    attr_reader :page_collection, :pwd, :duration
+
+    def print_success_summary
+      warn(successful_examples_summary)
+      warn(paintbrush { blue("\n  Created #{green(page_collection.page_paths.size)} pages.\n") })
+      warn(paintbrush { white("  View your documentation here: #{blue(Util.bundle_index_path)}\n") })
+    end
+
+    def print_failure_summary
+      page_collection.failures.each do |failure|
+        warn(failure.message)
+      end
+
+      warn(failure_summary)
+      warn("\nFailed examples:\n\n")
+      warn(failed_examples_summary)
+      $stderr.puts
+    end
+
+    def print_duration_summary
+      warn(duration_summary)
+    end
+
+    def failure_summary
+      examples = pluralize(page_collection.examples_count, 'example')
+      failures = pluralize(page_collection.failures.size, 'failure')
+      paintbrush do
+        red "#{page_collection.examples_count} #{examples}, #{page_collection.failures.size} #{failures}."
+      end
+    end
+
+    def successful_examples_summary
+      examples = pluralize(page_collection.examples_count, 'example')
+      failures = pluralize(page_collection.failures.size, 'failure')
+      paintbrush do
+        green "\n  #{cyan page_collection.examples_count} #{examples}, " \
+              "#{cyan page_collection.failures.size} #{failures}."
+      end
+    end
+
+    def pluralize(count, noun)
+      count.zero? || count > 1 ? "#{noun}s" : noun
+    end
+
+    def failed_examples_summary
+      page_collection.failures.map(&:spec).map do |spec|
+        paintbrush { red "  #{spec.path.relative_path_from(pwd)}:#{spec.location}" }
+      end.join("\n")
+    end
+
+    def duration_summary
+      formatted_spec_duration = format('%.2g', RSpecDocumentation::Spec.durations.sum)
+      formatted_total_duration = format('%.2g', duration)
+      paintbrush do
+        cyan "  Total build time: #{white formatted_total_duration} seconds, " \
+             "examples executed in #{white formatted_spec_duration} seconds.\n"
+      end
+    end
+  end
+end

data/lib/rspec_documentation/util.rb

@@ -10,6 +10,10 @@ module RSpecDocumentation
       bundle_dir.join(*relative_path.split.map { |segment| normalized_filename(segment) }).sub_ext('.html')
     end
 
+    def self.bundle_index_path
+      bundle_dir.join('index.html')
+    end
+
     def self.base_dir
       root_dir.join('rspec-documentation', 'pages')
     end
@@ -28,6 +32,10 @@ module RSpecDocumentation
       Pathname.new(path).basename.sub_ext('').sub(ORDERING_PREFIX_REGEXP, '')
     end
 
+    def self.path_id(path)
+      "path-id-#{Digest::SHA256.hexdigest(bundle_path(path).relative_path_from(bundle_dir).to_s)}"
+    end
+
     def self.href(path)
       relative_path = Pathname.new(path).relative_path_from(base_dir)
       url_root.join(*relative_path.split.map { |segment| normalized_filename(segment) }).sub_ext('.html')
@@ -39,6 +47,10 @@ module RSpecDocumentation
       Pathname.new(ENV.fetch('RSPEC_DOCUMENTATION_URL_ROOT'))
     end
 
+    def self.assets_root
+      url_root.join('assets')
+    end
+
     def self.normalized_filename(path)
       path.to_s.gsub(' ', '-').downcase.sub(ORDERING_PREFIX_REGEXP, '')
     end

data/lib/rspec_documentation.rb

@@ -12,17 +12,26 @@ require 'rake'
 
 require 'pathname'
 require 'securerandom'
+require 'digest'
+require 'json'
+require 'yaml'
+require 'date'
+require 'time'
 
 require_relative 'rspec_documentation/rspec'
 require_relative 'rspec_documentation/util'
-require_relative 'rspec_documentation/context'
+require_relative 'rspec_documentation/summary'
+require_relative 'rspec_documentation/project_initialization'
 require_relative 'rspec_documentation/configuration'
+require_relative 'rspec_documentation/stylesheet_bundle'
+require_relative 'rspec_documentation/javascript_bundle'
 require_relative 'rspec_documentation/document'
 require_relative 'rspec_documentation/parsed_document'
 require_relative 'rspec_documentation/html_element'
-require_relative 'rspec_documentation/ansi_html'
+require_relative 'rspec_documentation/formatters'
 require_relative 'rspec_documentation/spec'
 require_relative 'rspec_documentation/markdown_renderer'
+require_relative 'rspec_documentation/documentation'
 require_relative 'rspec_documentation/page_collection'
 require_relative 'rspec_documentation/page_tree'
 require_relative 'rspec_documentation/page_tree_element'
@@ -30,13 +39,17 @@ require_relative 'rspec_documentation/page_tree_element'
 # Internal module used by RSpec::Documentation to run examples and write output into an HTML document.
 module RSpecDocumentation
   class Error < StandardError; end
+  class MissingFileError < Error; end
 
   def self.root
     Pathname.new(File.dirname(__dir__))
   end
 
   def self.template(name, format = :html)
-    ERB.new(root.join('lib/templates', "#{name}.#{format}.erb").read)
+    ERB.new(
+      root.join('lib/templates', "#{name}.#{format}.erb").read,
+      eoutvar: "@eout#{SecureRandom.hex(16)}"
+    )
   end
 
   def self.theme(name)

data/lib/templates/000-Introduction.md.erb

@@ -0,0 +1,35 @@
+# Introduction
+
+Welcome to _RSpec Documentation_! This is your first documentation page.
+
+Here's an example spec:
+
+```rspec
+subject { true }
+
+it { is_expected.to be true }
+```
+
+And here's another:
+
+```rspec:html
+subject { '<h1>Title</h1><button class="btn btn-primary">Button</button>' }
+
+it { is_expected.to include 'Button' }
+```
+
+And here's one more:
+
+```rspec:ansi
+subject { "\e[35mSome purple text\e[0m" }
+
+it { is_expected.to include 'purple text' }
+```
+
+See the [documentation](https://docs.bob.frl/rspec-documentation) for more information on adding more content to your documentation.
+
+Run the `rspec-documentation` command any time you want to generate your documentation bundle:
+
+```console
+$ rspec-documentation
+```

data/lib/templates/010-Usage.md.erb

@@ -0,0 +1,3 @@
+# Usage
+
+Describe usage of your software here. Add _Markdown_ and _RSpec_ examples as needed.