rspec-documentation 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6eb4258635900a3617ddf6ab4cdfb7fe1d1cba62fbd8231f11437cf9b9734c6b
-  data.tar.gz: f5db6165cfd08d759765d4e50a0398bfdb0ab99dee84567fd535bd97cd30f0a4
+  metadata.gz: 8ce43727fba18b77d655b8ba4dc96b66b730823d4c44603a17d3033f70092daa
+  data.tar.gz: a53de33b4779cca033dfaa87eea7e60f473af09db986117c9a3d98cd9417d874
 SHA512:
-  metadata.gz: e25685a33fb2cc2bace75aa20c72f2b33407f2edec5a14840163cced2662fd852d3c87f8e4b31741b15825311365348f22cf5754b1850ddec1196bba64181a02
-  data.tar.gz: 3678422ca81bc09c5cd68db061b6a81746d21fb848824e229369721e727ac01f4fa4e517263ef9d47b8f1457f336d7dd6a0fdea0ee6ed63e498d62995f7c4102
+  metadata.gz: 7e44facb6a2ece7170e6111ced783f9e4a48780f478afbd257c6f30552816f6fcb22ab6733914f26c68168a71331f77c777f770e0e343c0301ad2be23855602e
+  data.tar.gz: ac708a5ee5336cb2c2aa9282704a94bb0d6d1f8120293af0cbc84e63d3914d88de25fdff7b942a1759f8f7a8d17e8252398ed3ba06d771c77023fa206bb42bc1

data/.rubocop.yml

@@ -1,4 +1,5 @@
 require:
+- 'rubocop-rspec-documentation'
 - 'rubocop-rake'
 - 'rubocop-rspec'
 

data/Gemfile

@@ -15,4 +15,5 @@ gem 'rspec-its', '~> 1.3'
 gem 'rubocop', '~> 1.52'
 gem 'rubocop-rake', '~> 0.6.0'
 gem 'rubocop-rspec', '~> 2.22'
+gem 'rubocop-rspec-documentation', require: false
 gem 'strong_versions', '~> 0.4.5'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-documentation (0.0.6)
+    rspec-documentation (0.0.8)
       htmlbeautifier (~> 1.4)
       kramdown (~> 2.4)
       kramdown-parser-gfm (~> 1.1)
@@ -19,7 +19,7 @@ GEM
     devpack (0.4.1)
     diff-lcs (1.5.0)
     htmlbeautifier (1.4.2)
-    i18n (1.13.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
     kramdown (2.4.0)
@@ -31,15 +31,16 @@ GEM
     paint (2.3.0)
     paintbrush (0.1.3)
     parallel (1.23.0)
-    parser (3.2.2.1)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
-    racc (1.6.2)
+      racc
+    racc (1.7.0)
     rainbow (3.1.1)
     rake (13.0.6)
     redcarpet (3.6.0)
-    regexp_parser (2.8.0)
+    regexp_parser (2.8.1)
     rexml (3.2.5)
-    rouge (4.1.1)
+    rouge (4.1.2)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -49,8 +50,8 @@ 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-file_fixtures (0.1.7)
+      rspec (~> 3.12)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
@@ -58,10 +59,10 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.52.0)
+    rubocop (1.52.1)
       json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.2.2.3)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
@@ -80,6 +81,9 @@ GEM
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)
+    rubocop-rspec-documentation (0.0.1)
+      rspec-documentation (~> 0.0.7)
+      rubocop (~> 1.52)
     ruby-progressbar (1.13.0)
     strong_versions (0.4.5)
       i18n (>= 0.5)
@@ -100,6 +104,7 @@ DEPENDENCIES
   rubocop (~> 1.52)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.22)
+  rubocop-rspec-documentation
   strong_versions (~> 0.4.5)
 
 BUNDLED WITH

data/README.md

@@ -13,7 +13,7 @@ There is no _DSL_ to learn and vanilla _RSpec_ examples are used to generate inp
 
 The following is an example _Markdown_ file.
 
-````console
+````markdown
 # An example test
 
 This is a very simple test:

data/exe/rspec-documentation

@@ -3,6 +3,21 @@
 
 require_relative '../lib/rspec/documentation'
 
+require 'optparse'
+
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: rspec-documentation [options]'
+  opts.on('-F', '--fail-fast', 'Abort the run after the first failure.') { |val| options[:fail_fast] = val if val }
+  opts.on('-b', '--backtrace', 'Enable full backtrace.') { |val| options[:full_backtrace] = val if val }
+end.parse!
+
+RSpec::Documentation.configure do |config|
+  config.fail_fast = options[:fail_fast] if options.key?(:fail_fast)
+  config.full_backtrace = options[:full_backtrace] if options.key?(:full_backtrace)
+end
+
 documentation = RSpec::Documentation.generate_documentation
 
 exit 1 if documentation.failed?

data/lib/rspec/documentation/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Documentation
-    VERSION = '0.0.6'
+    VERSION = '0.0.8'
   end
 end

data/lib/rspec_documentation/configuration.rb

@@ -4,9 +4,16 @@ module RSpecDocumentation
   # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
   class Configuration
     attr_reader :hooks
+    attr_accessor :consistent_height, :max_height, :fail_fast, :full_backtrace, :table_of_contents, :index_search
 
     def initialize
       @context_defined = false
+      @consistent_height = false
+      @max_height = '30rem'
+      @fail_fast = false
+      @full_backtrace = false
+      @table_of_contents = true
+      @index_search = true
       @hooks = {}
     end
 

data/lib/rspec_documentation/document.rb

@@ -18,6 +18,7 @@ module RSpecDocumentation
 
     def render
       parsed_document.execute_and_substitute_examples!
+
       if parsed_document.failures.empty?
         RSpecDocumentation.template('layout').result(binding)
       else
@@ -63,11 +64,17 @@ module RSpecDocumentation
     attr_reader :document, :path
 
     def parsed_document
-      @parsed_document ||= ParsedDocument.new(document, path: path)
+      @parsed_document ||= ParsedDocument.new(with_table_of_contents(document), path: path)
     end
 
     def gem_spec
       @gem_spec ||= Gem::Specification.load(Pathname.new(Dir.pwd).glob('*.gemspec').first.to_s)
     end
+
+    def with_table_of_contents(markdown)
+      return markdown unless RSpecDocumentation.configuration.table_of_contents
+
+      ['* TOC', '{:toc}', markdown].join("\n")
+    end
   end
 end

data/lib/rspec_documentation/documentation.rb

@@ -22,11 +22,14 @@ module RSpecDocumentation
       @failed || !page_collection.failures.empty?
     end
 
+    def page_collection
+      @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
+    end
+
     private
 
     def require_spec_helper
-      path = pwd.join('rspec-documentation/spec_helper.rb')
-      require path if path.file?
+      require Util.spec_helper_path if Util.spec_helper_path.file?
     end
 
     # Ensure `__rspec_documentation` shared context is always defined.
@@ -74,10 +77,6 @@ module RSpecDocumentation
       @page_paths ||= pwd.join('rspec-documentation/pages').glob('**/*.md')
     end
 
-    def page_collection
-      @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
-    end
-
     def pwd
       @pwd ||= Pathname.new(Dir.pwd)
     end

data/lib/rspec_documentation/formatters/html.rb

@@ -5,6 +5,8 @@ module RSpecDocumentation
     # Beautifies HTML received from a `subject`, renders the raw subject to be inserted directly
     # into the output document.
     class Html
+      DOCTYPE_TAG = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" ' \
+                    '"http://www.w3.org/TR/REC-html40/loose.dtd">'
       def initialize(subject:)
         @subject = subject
       end
@@ -16,7 +18,7 @@ module RSpecDocumentation
       end
 
       def rendered_output
-        subject
+        subject&.to_s&.sub(DOCTYPE_TAG, '')
       end
 
       def render_raw?

data/lib/rspec_documentation/kramdown_html_converter.rb

@@ -9,6 +9,19 @@ module Kramdown
         element.attr['class'] ||= 'rspec-documentation-table table'
         super
       end
+
+      def convert_header(element, indent)
+        [
+          '<div class="heading">',
+          super,
+          "<a class='heading-anchor' href='##{element.attr['id']}'>#{link_icon}</a>",
+          '</div>'
+        ].join
+      end
+
+      def link_icon
+        @link_icon ||= RSpecDocumentation.template(:link, :svg).result
+      end
     end
   end
 end

data/lib/rspec_documentation/page_collection.rb

@@ -6,6 +6,8 @@ module RSpecDocumentation
   class PageCollection
     attr_reader :failures, :page_paths
 
+    include Paintbrush
+
     def initialize(page_paths:)
       @page_paths = page_paths.sort_by(&:to_s)
       @buffer = {}
@@ -16,6 +18,7 @@ module RSpecDocumentation
       page_paths.zip(documents).each do |path, document|
         buffer[bundle_path_for(path)] = document.render
         failures.concat(document.failures)
+        break if RSpecDocumentation.configuration.fail_fast && !failures.empty?
       end
     end
 

data/lib/rspec_documentation/page_tree.rb

@@ -48,15 +48,15 @@ module RSpecDocumentation
       nodes.last == '<ol>' ? nodes.pop : nodes.push('</ol>')
     end
 
-    def build_tree(branch: structure, depth: 0)
-      normalized_paths.each do |path|
+    def build_tree(paths: normalized_paths, branch: structure, depth: 0)
+      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)
+        build_tree(paths: filtered_paths(path), branch: branch[first], depth: depth + 1)
       end
     end
 
@@ -74,6 +74,10 @@ module RSpecDocumentation
       end
     end
 
+    def filtered_paths(path)
+      normalized_paths.select { |normalized_path| normalized_path.to_s.start_with?(path.sub_ext('').to_s) }
+    end
+
     def page_tree_node(path:, child:)
       PageTreeElement.new(path: path, child: child, current_path: current_path).node
     end

data/lib/rspec_documentation/page_tree_element.rb

@@ -44,7 +44,7 @@ module RSpecDocumentation
 
     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}'>"
+        "data-search-tokens='#{Util.tokens(child).to_json}' data-parent-id='##{parent_path_id}'>"
     end
 
     def link

data/lib/rspec_documentation/parsed_document.rb

@@ -5,8 +5,16 @@ module RSpecDocumentation
   class ParsedDocument
     attr_reader :failures
 
+    include Paintbrush
+
     def initialize(document, path:)
-      @document = Kramdown::Document.new(document, input: 'GFM', syntax_highlighter: 'rouge')
+      @document = Kramdown::Document.new(
+        document,
+        toc_levels: 2...6,
+        input: 'GFM',
+        syntax_highlighter: 'rouge',
+        auto_ids: true
+      )
       @path = path
       @failures = []
     end
@@ -16,11 +24,11 @@ module RSpecDocumentation
     end
 
     def execute_and_substitute_examples!
+      print_empty if specs.empty?
       specs.each do |spec|
         spec.run
-        break failures << spec.failure unless spec.failure.nil?
-
-        spec.parent.children[spec.index] = spec_element(spec)
+        process_outcome(spec)
+        break if RSpecDocumentation.configuration.fail_fast && !failures.empty?
       end
     end
 
@@ -65,8 +73,34 @@ module RSpecDocumentation
       end
     end
 
+    def process_outcome(spec)
+      if spec.failure.nil?
+        print_success(spec)
+        spec.parent.children[spec.index] = spec_element(spec)
+      else
+        print_failure(spec)
+        failures << spec.failure
+      end
+    end
+
+    def relative_path
+      path.relative_path_from(Util.base_dir)
+    end
+
     def report_error(spec)
       $stderr.write(spec.failure.message)
     end
+
+    def print_empty
+      warn(paintbrush { cyan "    #{relative_path}" })
+    end
+
+    def print_success(spec)
+      warn(paintbrush { green "    #{relative_path}:#{spec.location}" })
+    end
+
+    def print_failure(spec)
+      warn(paintbrush { red "    #{relative_path}:#{spec.location}" })
+    end
   end
 end

data/lib/rspec_documentation/project_initialization.rb

@@ -9,6 +9,7 @@ module RSpecDocumentation
       print_welcome
       create_base_dir
       create_sample_files
+      create_spec_helper
       print_initialization_complete
     end
 
@@ -31,6 +32,13 @@ module RSpecDocumentation
       end
     end
 
+    def create_spec_helper
+      return if Util.spec_helper_path.exist?
+
+      Util.spec_helper_path.write(RSpecDocumentation.template(:spec_helper, :rb).result)
+      print_created(Util.spec_helper_path)
+    end
+
     def print_created(path)
       warn(paintbrush { "   #{green_b 'create'} #{cyan path.relative_path_from(pwd)}" })
     end

data/lib/rspec_documentation/rspec/failure.rb

@@ -39,9 +39,9 @@ module RSpecDocumentation
 
       def formatted_backtrace
         cause.backtrace
-             .take_while { |line| line.start_with?(Dir.pwd) }
-             .map { |line| paintbrush { red "    #{line.sub("#{Dir.pwd}/", '')}" } }
-             .join("\n")
+             &.take_while { |line| RSpecDocumentation.configuration.full_backtrace || line.start_with?(Dir.pwd) }
+             &.map { |line| paintbrush { red "    #{line.sub("#{Dir.pwd}/", '')}" } }
+             &.join("\n")
       end
 
       def indented(text)

data/lib/rspec_documentation/util.rb

@@ -14,6 +14,10 @@ module RSpecDocumentation
       bundle_dir.join('index.html')
     end
 
+    def self.spec_helper_path
+      root_dir.join('rspec-documentation/spec_helper.rb')
+    end
+
     def self.base_dir
       root_dir.join('rspec-documentation', 'pages')
     end
@@ -29,7 +33,11 @@ module RSpecDocumentation
     end
 
     def self.label(path)
-      Pathname.new(path).basename.sub_ext('').sub(ORDERING_PREFIX_REGEXP, '')
+      Pathname.new(path).basename.sub_ext('').sub(ORDERING_PREFIX_REGEXP, '').to_s
+    end
+
+    def self.tokens(path)
+      label(path).downcase.split
     end
 
     def self.path_id(path)
@@ -52,7 +60,9 @@ module RSpecDocumentation
     end
 
     def self.normalized_filename(path)
-      path.to_s.gsub(' ', '-').downcase.sub(ORDERING_PREFIX_REGEXP, '')
+      path.split.map do |segment|
+        segment.to_s.gsub(' ', '-').downcase.sub(ORDERING_PREFIX_REGEXP, '')
+      end.join('/')
     end
   end
 end

data/lib/templates/layout.css.erb

@@ -7,6 +7,7 @@
    MonokaiSublime, Pastie, ThankfulEyes, Tulip */
 <%= Rouge::Theme.find('molokai').render(scope: '.highlight') %>
 
+<% if RSpecDocumentation.configuration.consistent_height %>
 /* https://stackoverflow.com/a/61587938 */
 .consistent-height .tab-content {
   display: flex;
@@ -22,6 +23,7 @@
 .consistent-height .tab-content > .active {
   visibility: visible;
 }
+<% end %>
 
 @keyframes fade-in {
   from {
@@ -33,6 +35,35 @@
   }
 }
 
+[data-bs-theme="dark"] .table-of-contents-wrapper {
+  border-color: #444242;
+  background-color: #4e4e4e55;
+}
+
+[data-bs-theme="dark"] .table-of-contents-wrapper .title {
+  border-color: #444242;
+}
+
+[data-bs-theme="dark"] table.rspec-documentation-table td, [data-bs-theme="dark"] table.rspec-documentation-table th {
+  border: 1px solid #4e4e4e;
+}
+
+[data-bs-theme="dark"] table.rspec-documentation-table tr:hover td {
+  background-color: #325d8833;
+}
+
+[data-bs-theme="dark"] .header-wrapper {
+  background-color: #212121;
+}
+
+[data-bs-theme="dark"] .form-control {
+  color: #b2b2b2;
+}
+
+[data-bs-theme="dark"] input.form-control::placeholder {
+  color: #999;
+}
+
 body {
   opacity: 0;
   animation: fade-in ease-in 1;
@@ -43,6 +74,11 @@ body {
 
 .header-wrapper {
   background-color: #fff;
+  z-index: 100000;
+}
+
+table.rspec-documentation-table tr:hover td {
+  background-color: #8a8d9124;
 }
 
 table.rspec-documentation-table td, table.rspec-documentation-table th {
@@ -50,12 +86,68 @@ table.rspec-documentation-table td, table.rspec-documentation-table th {
   padding: 0.5rem 1rem;
 }
 
-[data-bs-theme="dark"] table.rspec-documentation-table td, [data-bs-theme="dark"] table.rspec-documentation-table th {
-  border: 1px solid #4e4e4e;
+.index-search {
+  margin-bottom: 1rem;
 }
 
-[data-bs-theme="dark"] .header-wrapper {
-  background-color: #212121;
+.page-tree li.search-active {
+  list-style: circle;
+  list-style-color: green;
+}
+
+.table-of-contents-wrapper {
+  position: relative;
+  padding: 0.4rem 0.8rem;
+  background-color: #c7c7c729;
+  display: inline-block;
+  float: right;
+  margin-left: 1rem;
+  margin-bottom: 0.4rem;
+  border-style: solid;
+  border-width: 1px;
+  border-radius: 10px;
+  border-color: #cfcfcf;
+}
+
+.table-of-contents-wrapper .title {
+  text-align: center;
+  border-bottom: 1px solid #cfcfcf;
+  margin-bottom: 0.2rem;
+  padding-bottom: 0.2rem;
+  font-weight: bold;
+}
+
+#markdown-toc {
+  list-style: disc;
+  line-height: 1.8rem;
+  padding: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+}
+
+#markdown-toc ul {
+  padding-left: 1rem;
+}
+
+.heading-anchor {
+  padding: 0.2rem;
+  vertical-align: middle;
+  display: inline-block;
+  padding-bottom: 0.4rem;
+  scroll-padding-top: 5rem;
+}
+
+.heading-anchor svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+.heading-anchor svg path {
+  fill: #7ac0f8;
+}
+
+#markdown-toc li a {
+  text-decoration: none;
 }
 
 .theme-switcher {
@@ -86,9 +178,21 @@ h1.title a {
   text-decoration: none;
 }
 
+.content h1, .content h2, .content h3, .content h4, .content h5, .content h6 {
+  display: inline-block;
+  scroll-margin-top: 6rem;
+}
+
+.heading-anchor {
+  font-size: 0.8rem;
+  text-decoration: none;
+  color: rgb(122,192,248);
+}
+
 .code {
   font-family: monospace;
-  max-height: 30rem;
+  font-size: 0.9rem;
+  max-height: <%= RSpecDocumentation.configuration.max_height %>;
   overflow-y: auto;
 }
 

data/lib/templates/layout.html.erb

@@ -1,6 +1,7 @@
 <html>
   <head>
     <meta charset="utf-8" />
+    <title><%= title %></title>
     <%= RSpecDocumentation.template(:stylesheet_links).result(binding) %>
     <%= RSpecDocumentation.hook(:after_head) %>
   </head>
@@ -15,11 +16,19 @@
 
       <div class="row flex-nowrap">
         <div class="col-sm-2 fs-6 mt-1 ms-3 me-3">
-          <ol class="page-tree hidden position-fixed">
-            <% page_tree.elements.each do |element| %>
-              <%= element %>
+          <div class="position-fixed">
+            <% if RSpecDocumentation.configuration.index_search %>
+            <div class="index-search">
+              <input type="text" class="index-search-field form-control" placeholder="Search (Ctrl+/)" />
+            </div>
             <% end %>
-          </ol>
+
+            <ol class="page-tree hidden">
+              <% page_tree.elements.each do |element| %>
+                <%= element %>
+              <% end %>
+            </ol>
+          </div>
         </div>
 
         <%= RSpecDocumentation.hook(:before_content) %>