rspec-documentation 0.0.1 → 0.0.2

data/lib/rspec_documentation/rspec/example_group.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module RSpec
+    # Replicates behaviour of a regular RSpec example group but also defines `it_documents` as an
+    # alias for `it`.
+    class ExampleGroup < ::RSpec::Core::ExampleGroup
+      def self.it_documents(described_object, &block)
+        raise Error, 'Must pass an example object to `it_documents`' if described_object.nil?
+
+        metadata = { described_object: described_object }
+        ::RSpec::Core::Example.new(self, 'documentation', metadata, block)
+      end
+
+      class << self
+        def method_missing(...)
+          RSpecDocumentation.context.public_send(...)
+        end
+
+        def respond_to_missing?(*args)
+          RSpecDocumentation.context.respond_to_missing?(*args)
+        end
+      end
+    end
+  end
+end

data/lib/rspec_documentation/rspec/failure.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module RSpec
+    # Stores information about a failed RSpec example. Thin wrapper around `RSpec::Failure`.
+    class Failure
+      def initialize(cause:, spec:)
+        @cause = cause
+        @spec = spec
+      end
+
+      def message
+        "\n#{formatted_header}\n\n#{formatted_source}\n#{formatted_cause}\n\n"
+      end
+
+      private
+
+      attr_reader :cause, :spec
+
+      def formatted_header
+        "\e[1;37m#{indented('Failure in example')}:\e[0m"
+      end
+
+      def formatted_source
+        "\e[1;34m#{indented(spec.source)}\e[0m"
+      end
+
+      def formatted_cause
+        "\e[31m#{indented(cause.message)}\e[0m"
+      end
+
+      def indented(text)
+        text.split("\n").map { |line| "    #{line}" }.join("\n")
+      end
+    end
+  end
+end

data/lib/rspec_documentation/rspec/reporter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module RSpec
+    # RSpec reporter, compliant with RSpec::Core::Reporter. Stores outcomes of specs.
+    class Reporter
+      attr_reader :passed_examples, :failed_examples
+
+      def initialize
+        @passed_examples = []
+        @failed_examples = []
+      end
+
+      def described_object
+        raise Error, 'Code block did not contain an example.' if passed_examples.empty? && failed_examples.empty?
+
+        passed_examples&.first&.metadata&.fetch(:described_object)
+      end
+
+      def report(*_); end
+
+      def finish(*_); end
+
+      def example_passed(example)
+        raise Error, 'Cannot define more than one example per code block.' if passed_examples.size >= 1
+
+        passed_examples << example
+      end
+
+      def example_group_started(*_); end
+
+      def example_group_finished(*_); end
+
+      def example_started(*_); end
+
+      def example_finished(*_); end
+
+      def example_failed(example)
+        failed_examples << example
+      end
+
+      def fail_fast_limit_met?(*_); end
+    end
+  end
+end

data/lib/rspec_documentation/rspec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/example_group'
+require_relative 'rspec/reporter'
+require_relative 'rspec/failure'
+
+module RSpecDocumentation
+  # Provides various classes that wrap or interface RSpec internals.
+  module RSpec
+    def self.with_failure_notifier(callable, &block)
+      ::RSpec::Support.with_failure_notifier(callable, &block)
+    end
+  end
+end

data/lib/rspec_documentation/spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+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
+
+    def initialize(spec:, format:, parent:, location:, index:)
+      @spec = spec
+      @format = format.empty? ? :plaintext : format.to_sym
+      @parent = parent
+      @location = location
+      @index = index
+      @failures = []
+      @reporter = RSpec::Reporter.new
+    end
+
+    def described_object
+      @described_object ||= reporter.described_object
+    end
+
+    def source
+      spec
+    end
+
+    def failure
+      failures.first
+    end
+
+    def run
+      RSpec.with_failure_notifier(failure_notifier) do
+        example_group.run(reporter)
+      end
+    end
+
+    private
+
+    attr_reader :spec, :failures, :reporter
+
+    def examples
+      @examples ||= example_group.examples
+    end
+
+    def example_group
+      # rubocop:disable Style/DocumentDynamicEvalDefinition, Security/Eval
+      @example_group ||= binding.eval(
+        <<-SPEC, __FILE__, __LINE__.to_i
+          RSpec::ExampleGroup.describe do
+            #{spec}
+          end
+        SPEC
+      )
+      # rubocop:enable Style/DocumentDynamicEvalDefinition, Security/Eval
+    end
+
+    def failure_notifier
+      proc do |failure|
+        failures << RSpec::Failure.new(cause: failure, spec: self)
+      end
+    end
+  end
+end

data/lib/rspec_documentation/util.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Misc utility classes for functionality shared between components, helpers for path normalization.
+  class Util
+    ORDERING_PREFIX_REGEXP = /^[0-9]+-/.freeze
+
+    def self.bundle_path(path)
+      relative_path = Pathname.new(path).relative_path_from(base_dir)
+      bundle_dir.join(*relative_path.split.map { |segment| normalized_filename(segment) }).sub_ext('.html')
+    end
+
+    def self.base_dir
+      root_dir.join('rspec-documentation', 'pages')
+    end
+
+    def self.bundle_dir
+      return root_dir.join('rspec-documentation', 'bundle') unless ENV.key?('RSPEC_DOCUMENTATION_BUNDLE_PATH')
+
+      Pathname.new(ENV.fetch('RSPEC_DOCUMENTATION_BUNDLE_PATH'))
+    end
+
+    def self.root_dir
+      Pathname.new(Dir.pwd)
+    end
+
+    def self.label(path)
+      Pathname.new(path).basename.sub_ext('').sub(ORDERING_PREFIX_REGEXP, '')
+    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')
+    end
+
+    def self.url_root
+      return bundle_dir unless ENV.key?('RSPEC_DOCUMENTATION_URL_ROOT')
+
+      Pathname.new(ENV.fetch('RSPEC_DOCUMENTATION_URL_ROOT'))
+    end
+
+    def self.normalized_filename(path)
+      path.to_s.gsub(' ', '-').downcase.sub(ORDERING_PREFIX_REGEXP, '')
+    end
+  end
+end

data/lib/rspec_documentation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'htmlbeautifier'
+require 'kramdown'
+require 'kramdown-parser-gfm'
+require 'paintbrush'
+require 'redcarpet'
+require 'rouge'
+require 'rouge/plugins/redcarpet'
+require 'rspec'
+require 'rake'
+
+require 'pathname'
+require 'securerandom'
+
+require_relative 'rspec_documentation/rspec'
+require_relative 'rspec_documentation/util'
+require_relative 'rspec_documentation/context'
+require_relative 'rspec_documentation/configuration'
+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/spec'
+require_relative 'rspec_documentation/markdown_renderer'
+require_relative 'rspec_documentation/page_collection'
+require_relative 'rspec_documentation/page_tree'
+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
+
+  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)
+  end
+
+  def self.theme(name)
+    ERB.new(root.join('lib/templates/themes', "#{name}.css").read).result(binding)
+  end
+
+  def self.context
+    yield configuration.context if block_given?
+    configuration.context
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.configuration
+    @configuration ||= RSpecDocumentation::Configuration.new
+  end
+end

data/lib/tasks/rspec/documentation/generate.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+namespace :rspec do
+  namespace :documentation do
+    desc 'Generates documentation from Markdown located in rpsec-documentation/pages'
+    task :generate do
+      RSpec::Documentation.generate_documentation
+    end
+  end
+end

data/lib/templates/footer.html.erb

@@ -0,0 +1 @@
+<hr/>

data/lib/templates/header.html.erb

@@ -0,0 +1,7 @@
+<div class="header p-3 m-3 w-90 text-end">
+  <h1 class="title"><%= title %></h1>
+  <span class="separator border-end pb-2 ms-2 me-2"></span>
+  <span class="version"><%= version %></span>
+</div>
+
+<hr/>

data/lib/templates/layout.css.erb

@@ -0,0 +1,39 @@
+.code {
+  font-family: monospace;
+  max-height: 30rem;
+  overflow-y: auto;
+}
+
+h1.title {
+  display: inline;
+}
+
+.header .separator {
+  display: inline-block;
+  height: 2.5rem;
+}
+
+.version {
+  color: #bbb;
+  font-size: 2rem;
+}
+
+.ansi-html {
+  display: inline-block;
+  background-color: #2e2e2e;
+  border: 5px solid #2e2e2e;
+  border-radius: 10px;
+}
+
+.ansi-html .ansi-color-0 { color: #555555; }
+.ansi-html .ansi-color-1 { color: #ff0000; }
+.ansi-html .ansi-color-2 { color: #47ff47; }
+.ansi-html .ansi-color-3 { color: #e9e947; }
+.ansi-html .ansi-color-4 { color: #49a0dd; }
+.ansi-html .ansi-color-5 { color: #8d7eeb; }
+.ansi-html .ansi-color-6 { color: #2eecff; }
+.ansi-html .ansi-color-7 { color: #ffffff; }
+.ansi-html .ansi-color-9 { color: #606060; }
+.ansi-html .ansi-color-reset { color: #dddddd; }
+
+<%= Rouge::Themes::Github.render %>

data/lib/templates/layout.html.erb

@@ -0,0 +1,100 @@
+<html>
+  <head>
+    <style>
+
+       /* cerulean, cosmo, cyborg, darkly, flatly, journal, litera, lumen, lux, materia, minty, morph,
+          pulse, quartz, sandstone, simplex, sketchy, slate, solar, spacelab, superhero, united, vapor,
+          yeti, zephyr */
+      <%= RSpecDocumentation.theme(:materia) %>
+
+      /* Base16, BlackWhiteTheme, Colorful, Github, Gruvbox, IgorPro, Magritte, Molokai, Monokai,
+         MonokaiSublime, Pastie, ThankfulEyes, Tulip */
+      <%= Rouge::Themes::Molokai.render %>
+
+      /* https://stackoverflow.com/a/61587938 */
+      .consistent-height .tab-content {
+        display: flex;
+      }
+
+      .consistent-height .tab-content > .tab-pane {
+        display: block; /* undo "display: none;" */
+        visibility: hidden;
+        margin-right: -100%;
+        width: 100%;
+      }
+
+      .consistent-height .tab-content > .active {
+        visibility: visible;
+      }
+
+
+      .code {
+        font-family: monospace;
+        max-height: 30rem;
+        overflow-y: auto;
+      }
+
+      h1.title {
+        display: inline;
+      }
+
+      .header .separator {
+        display: inline-block;
+        height: 2.5rem;
+      }
+
+      .version {
+        font-size: 2rem;
+      }
+
+      .highlight {
+        padding: 1rem;
+      }
+
+      .ansi-html {
+        display: inline-block;
+        background-color: #2e2e2e;
+        border: 5px solid #2e2e2e;
+        border-radius: 10px;
+      }
+
+      .ansi-html .ansi-color-0 { color: var(--bs-dark); }
+      .ansi-html .ansi-color-1 { color: var(--bs-red); }
+      .ansi-html .ansi-color-2 { color: var(--bs-green); }
+      .ansi-html .ansi-color-3 { color: var(--bs-yellow) }
+      .ansi-html .ansi-color-4 { color: var(--bs-blue); }
+      .ansi-html .ansi-color-5 { color: var(--bs-purple); }
+      .ansi-html .ansi-color-6 { color: var(--bs-cyan); }
+      .ansi-html .ansi-color-7 { color: var(--bs-white); }
+      .ansi-html .ansi-color-9 { color: var(--bs-light); }
+      .ansi-html .ansi-color-reset { color: var(--bs-light);; }
+
+    </style>
+  </head>
+
+  <body>
+    <div class="container m-3 p-3">
+      <div class="bg-light sticky-top">
+        <%= header %>
+      </div>
+
+      <div class="row">
+        <div class="col-auto page-tree fs-6 mt-1 ms-3 me-3">
+          <% page_tree.elements.each do |element| %>
+            <%= element %>
+          <% end %>
+        </div>
+
+        <div class="col">
+          <%= html %>
+        </div>
+      </div>
+      <%= footer %>
+    </div>
+
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.3/js/bootstrap.bundle.min.js"
+            integrity="sha512-i9cEfJwUwViEPFKdC1enz4ZRGBj8YQo6QByFTF92YXHi7waCqyexvRD75S5NVTsSiTv7rKWqG9Y5eFxmRsOn0A=="
+            crossorigin="anonymous"
+            referrerpolicy="no-referrer"></script>
+  </body>
+</html>

data/lib/templates/tabbed_spec.html.erb

@@ -0,0 +1,119 @@
+<div class="modal fade" id="modal-<%= element_id %>-side-by-side" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="staticBackdropLabel" aria-hidden="true">
+  <div class="modal-dialog modal-xl">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title" id="modal-<%= element_id %>-side-by-side-label">Side-by-side view</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+      </div>
+      <div class="modal-body">
+        <div class="container p-3">
+          <div class="row border">
+            <div class="col border">
+              <div class="p-3 mb-5 code highlight">
+                <%= code_source.gsub("\n", '<br/>').gsub('  ', '&nbsp;&nbsp;') %>
+              </div>
+            </div>
+
+            <% unless html_source.nil? %>
+            <div class="col border">
+              <div class="p-3 mb-5 code highlight">
+                <%= html_source.gsub("\n", '<br/>').gsub('  ', '&nbsp;&nbsp;') %>
+              </div>
+            </div>
+            <% end %>
+
+            <div class="col border">
+              <div class="p-3 mb-5 <%= html_source.nil? ? 'code highlight' : nil %>">
+                <%= rendered_result %>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="consistent-height">
+
+  <ul class="nav nav-tabs" id="html-tabs-<%= element_id %>" role="tablist">
+
+    <li class="nav-item" role="presentation">
+      <button class="nav-link active"
+              id="code-source-<%= element_id %>-tab"
+              data-bs-toggle="tab"
+              data-bs-target="#code-source-<%= element_id %>"
+              type="button"
+              role="tab"
+              aria-controls="code-source"
+              aria-selected="true">Code</button>
+    </li>
+
+    <% unless html_source.nil? %>
+    <li class="nav-item" role="presentation">
+      <button class="nav-link"
+              id="html-source-<%= element_id %>-tab"
+              data-bs-toggle="tab"
+              data-bs-target="#html-source-<%= element_id %>"
+              type="button"
+              role="tab"
+              aria-controls="html-source"
+              aria-selected="true">HTML</button>
+    </li>
+    <% end %>
+
+    <li class="nav-item" role="presentation">
+      <button class="nav-link"
+              id="rendered-<%= element_id %>-tab"
+              data-bs-toggle="tab"
+              data-bs-target="#rendered-<%= element_id %>"
+              type="button"
+              role="tab"
+              aria-controls="rendered"
+              aria-selected="false"><%= html_source.nil? ? 'Output' : 'Rendered HTML' %></button>
+    </li>
+
+    <li class="nav-item bs-auto ms-auto mb-2">
+      <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#modal-<%= element_id %>-side-by-side">
+        View Side-by-side
+      </button>
+    </li>
+
+  </ul>
+
+  <div class="tab-content" id="html-tab-content-<%= element_id %>">
+
+    <div class="tab-pane fade show active"
+         id="code-source-<%= element_id %>"
+         role="tabpanel"
+         aria-labelledby="code-source-<%= element_id %>-tab">
+      <div class="p-3 mb-5 code highlight">
+        <%= code_source.gsub("\n", '<br/>').gsub('  ', '&nbsp;&nbsp;') %>
+      </div>
+    </div>
+
+    <% unless html_source.nil? %>
+    <div class="tab-pane fade"
+         id="html-source-<%= element_id %>"
+         role="tabpanel"
+         aria-labelledby="html-source-<%= element_id %>-tab">
+      <div class="p-3 mb-5 code highlight">
+        <%= html_source.gsub("\n", '<br/>').gsub('  ', '&nbsp;&nbsp;') %>
+      </div>
+    </div>
+    <% end %>
+
+    <div class="tab-pane fade"
+         id="rendered-<%= element_id %>"
+         role="tabpanel"
+         aria-labelledby="rendered-<%= element_id %>-tab">
+      <div class="p-3 mb-5 <%= html_source.nil? ? 'code highlight' : nil %>">
+        <%= rendered_result %>
+      </div>
+    </div>
+  </div>
+</div>
+